Functions

Open Config Data

Opens a reference to the configuration data found in a platform-independent

configuration file.

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• configuration file path —

configuration file path is the path to the platform-independent configuration file.

• create file if necessary (T) —

create file if necessary (T) configures the VI to create the file specified in configuration file path
if the file does not exist. You must set create file if necessary (T) to the default value of TRUE for
the VI to create the file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum —

refnum is the reference number of the configuration data.

• file created? —

file created? returns TRUE if the configuration file operation creates a file.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1501

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

• Read Key (Boolean) VI

• Read Key (Double) VI
• Read Key (I32) VI
• Read Key (Path) VI
• Read Key (String) VI
• Read Key (U32) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key (Boolean) VI

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

1502 ni.com
 Functions

Inputs/Outputs
• section —

section is the name of the section from which to read the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to read.

• default value —

default value is the value to return if the VI does not find the key in the specified section or if an
error occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• value —

value is the value of the key.

• error out —

© National Instruments 1503

 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key (Double) VI

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• section —

section is the name of the section from which to read the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to read.

• default value —

1504 ni.com
 Functions

default value is the value to return if the VI does not find the key in the specified section or if an
error occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• value —

value is the value of the key.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key (I32) VI

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

© National Instruments 1505

 Functions

Inputs/Outputs
• section —

section is the name of the section from which to read the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to read.

• default value —

default value is the value to return if the VI does not find the key in the specified section or if an
error occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• value —

value is the value of the key.

• error out —

error out contains error information. This output provides standard error out functionality.

1506 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key (Path) VI

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• section —

section is the name of the section from which to read the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to read.

• default value —

default value is the value to return if the VI does not find the key in the specified section or if an
error occurs.

• error in (no error) —

© National Instruments 1507

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• value —

value is the value of the key.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key (String) VI

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

1508 ni.com
 Functions

Inputs/Outputs
• section —

section is the name of the section from which to read the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to read.

• default value —

default value is the value to return if the VI does not find the key in the specified section or if an
error occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• read raw string? (F) —

read raw string? specifies whether the string was written without escaping unprintable and
backslash (\) characters.

If FALSE (default), the VI replaces any unprintable characters in the string, such as <ESC>, with a
backslash and two Hex characters (\xx). If TRUE, the VI does not convert the unprintable
characters in the string.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• value —

value is the value of the key.

• error out —

© National Instruments 1509

 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Read Key (U32) VI

Reads a value associated with a key in a specified section from the configuration data
identified by refnum. If the key does not exist, the VI returns the default value. This VI
supports multibyte characters in strings. Wire data to the default value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• section —

section is the name of the section from which to read the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to read.

• default value —

1510 ni.com
 Functions

default value is the value to return if the VI does not find the key in the specified section or if an
error occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• value —

value is the value of the key.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Write Key

Writes a value to a key in a specified section of the configuration data identified by

refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

Format the content of an .ini file correctly when you use this VI.

© National Instruments 1511

 Functions

• Write Key (Boolean) VI

• Write Key (Double) VI
• Write Key (I32) VI
• Write Key (Path) VI
• Write Key (String) VI
• Write Key (U32) VI

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Write Key (Boolean) VI

Writes a value to a key in a specified section of the configuration data identified by
refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

Format the content of an .ini file correctly when you use this VI.

1512 ni.com
 Functions

Inputs/Outputs
• section —

section is the name of the section in which to write the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to write.

• value —

value is the value to write to the key.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 1513

 Functions

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Write Key (Double) VI

Writes a value to a key in a specified section of the configuration data identified by
refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• use system decimal point (T) —

use system decimal point specifies whether to use the localized decimal separator. The default
is TRUE.

• section —

section is the name of the section in which to write the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to write.

• value —

1514 ni.com
 Functions

value is the value of the key to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• precision (6) —

precision is the number of digits after the decimal point. The default is 6.

• format (fractional) —

format is the format of the number.

Fractional
0
(default)
1 Engineering
2 Exponential

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration

© National Instruments 1515

 Functions

(INI)\Configuration (INI) File.lvproj

Write Key (I32) VI

Writes a value to a key in a specified section of the configuration data identified by
refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• section —

section is the name of the section in which to write the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to write.

• value —

value is the value of the key to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

1516 ni.com
 Functions

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Write Key (Path) VI

Writes a value to a key in a specified section of the configuration data identified by
refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

Format the content of an .ini file correctly when you use this VI.

© National Instruments 1517

 Functions

Inputs/Outputs
• section —

section is the name of the section in which to write the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to write.

• value —

value is the value of the key to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

1518 ni.com
 Functions

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Write Key (String) VI

Writes a value to a key in a specified section of the configuration data identified by
refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• section —

section is the name of the section in which to write the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to write.

• value —

value is the value of the key to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

© National Instruments 1519

 Functions

• write raw string? (F) —

write raw string? specifies whether to write the string without escaping unprintable and
backslash (\) characters.

If FALSE (default), the VI converts any backslashes (\) to double backslashes (\\) and replaces
any remaining unprintable characters in the string, such as <ESC>, with a backslash and two
Hex characters (\xx). If TRUE, the VI does not convert the unprintable characters in the string.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Write Key (U32) VI

Writes a value to a key in a specified section of the configuration data identified by
refnum. This VI modifies data in memory. To write data to disk, use the Close Config
Data VI. Wire data to the value input to determine the polymorphic instance to use or
manually select the instance.

1520 ni.com
 Functions

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• section —

section is the name of the section in which to write the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to write.

• value —

value is the value of the key to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1521

 Functions

If key exists, the VI replaces the existing value. If key does not exist, the VI adds the
key/value pair to the end of the specified section. If section does not exist, the VI adds
section, with the key/value pair, to the end of the configuration data.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Remove Key

Removes a key in a specified section from the configuration data identified by refnum.

Inputs/Outputs
• section —

section is the name of the section from which to remove the specified key.

• refnum —

refnum is the reference number of the configuration data.

• key —

key is the name of the key to remove.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

1522 ni.com
 Functions

refnum out is the reference number of the configuration data.

• found? —

found? is TRUE if the VI found the key in the specified section.

• error out —

error out contains error information. This output provides standard error out functionality.

Remove Section

Removes a section from the configuration data identified by refnum.

Inputs/Outputs
• section —

section is the name of the section to remove.

• refnum —

refnum is the reference number of the configuration data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• section exists? —

section exists? is TRUE if the VI found the specified section.

© National Instruments 1523

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Close Config Data

Writes data to the platform-independent configuration file identified by refnum and

then closes the reference to that file.

Inputs/Outputs
• refnum —

refnum is the reference number of the configuration data.

• write file if changed (T) —

write file if changed (T) configures the VI to write the configuration data to the platform-
independent configuration file you specify with the Open Config Data VI. You must set write file
if changed (T) to the default value of TRUE for the VI to write the configuration data. If the value
is FALSE, the VI does not write the configuration data.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

If an error occurs before this node executes, the node only closes the reference passed to it.

• file path —

file path is the path to the configuration file.

• error out —

error out contains error information. This output provides standard error out functionality.

1524 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Configuration
(INI)\Configuration (INI) File.lvproj

Get Key Names

Gets the names of all keys in the specified section from the configuration data
identified by refnum.

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• section —

section is the name of the section from which to get the key names.

• refnum —

refnum is the reference number of the configuration data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• section exists? —

© National Instruments 1525

 Functions

section exists? is TRUE if the VI found the specified section.

• key names —

key names contains the names of all keys in the section, in the order in which they appear in the
file.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Section Names

Gets the names of all sections from the configuration data identified by refnum.

Format the content of an .ini file correctly when you use this VI.

Inputs/Outputs
• refnum —

refnum is the reference number of the configuration data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the configuration data.

• section names —

section names contains the names of all sections in refnum.

• error out —

1526 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Not A Config Data Refnum

Determines whether a configuration data refnum is valid.

This VI considers a configuration data refnum to be invalid if you do not open the
reference with the Open Config Data VI, the file referenced does not exist, or the
reference is already closed when passed to this VI.

Inputs/Outputs
• refnum —

refnum is the reference number of the configuration data.

• not a config data refnum —

not a config data refnum is TRUE if refnum is not a valid configuration data refnum.

TDM Streaming

Use the TDM Streaming VIs and functions to read and write waveforms and waveform
properties to binary measurement files (.tdms).

Note Some functions on this palette do not work with real-time operating
systems.

The VIs and functions on this palette can return TDM streaming error codes.

© National Instruments 1527

 Functions

Palette
Description
Object
Opens a .tdms file for reading or writing. You also can use this function to create a new
TDMS Open
file or replace an existing file. Use the TDMS Close function to close the reference to
Function
the file.
TDMS Write Streams data to the specified .tdms file. The data subset to write is determined by the
Function values you identify in the group name in and channel name(s) in inputs.
Reads the specified .tdms file and returns data in a format specified by the data type
TDMS Read
input. If data has scaling information, this VI automatically scales the data. Use the
Function
count and offset inputs to read a specified subset of the data.
TDMS Close
Closes the .tdms file you opened with the TDMS Open function.
Function
TDMS List
Provides a list of group and channel names contained within the .tdms file specified in
Contents
the .tdms file input.
Function
Sets the properties of the specified .tdms file, channel group, or channel. If you wire
the group name and channel name inputs with values, the function writes the
properties at the channel level. Wiring only the group name input with a value writes
TDMS Set
the properties at the channel group level. If both group name and channel name
Properties
inputs contain no values, the properties become file-specific. If you wire the channel
Function
name input with a value, you must also wire a value to the group name input. You
must close the reference to the .tdms file or flush data to the .tdms file for changes to
take effect.
Returns the properties of the specified .tdms file, channel group, or channel. If you
wire the group name and channel name inputs with values, the function searches for
TDMS Get properties at the channel level. Wiring only the group name input with a value
Properties searches for properties at the channel group level. If both group name and channel
Function name inputs contain no values, the function searches for properties at the root level
of the .tdms file. If you wire the channel name input with a value, you must also wire a
value to the group name input.
Writes all buffers of the .tdms file data to the file identified by the tdms file input. Data
TDMS Flush written to a .tdms file often resides in a buffer until the buffer fills up or until you close
Function the file. This function forces the operating system to write any buffer data to the .tdms
file.

TDMS File Opens the .tdms file specified in the file in input and presents the file data in the
Viewer TDMS File Viewer dialog box.

1528 ni.com
 Functions

Palette
Description
Object
TDMS
Defragments the .tdms file data specified in the file path input. Use this function to
Defragment
clean up your .tdms data when it becomes cluttered, and increase performance.
Function

Use the Advanced TDMS VIs and functions to perform advanced file I/O operations,
such as asynchronous reads and writes, on .tdms files. You can use these VIs and
Advanced functions to read data from an existing .tdms file, write data to a new .tdms file, or
TDMS replace subsets of data in an existing .tdms file. You also can use these VIs and
functions to convert the file format version of a .tdms file or to create scaling
information for unscaled data.

Unsupported Functions on Real-Time Operating Systems

The following functions on this palette do not work with real-time operating systems,
such as Phar Lap ETS, VxWorks, and NI Linux Real-Time:

• TDMS Advanced Asynchronous Read

• TDMS Advanced Asynchronous Read (Data Ref)
• TDMS Advanced Asynchronous Write
• TDMS Advanced Asynchronous Write (Data Ref)
• TDMS Configure Asynchronous Reads
• TDMS Configure Asynchronous Reads (Data Ref)
• TDMS Configure Asynchronous Writes
• TDMS Configure Asynchronous Writes (Data Ref)
• TDMS File Viewer
• TDMS Generate Random Data
• TDMS Get Asynchronous Read Status
• TDMS Get Asynchronous Read Status (Data Ref)
• TDMS Get Asynchronous Write Status
• TDMS Get Asynchronous Write Status (Data Ref)
• TDMS Reserve File Size
• TDMS Start Asynchronous Reads
• TDMS Stop Asynchronous Reads

© National Instruments 1529

 Functions

TDMS Open Function

Opens a .tdms file for reading or writing. You also can use this function to create a new
file or replace an existing file. Use the TDMS Close function to close the reference to the
file.

Inputs/Outputs
• create index file? (T) —

create index file? specifies whether LabVIEW automatically generates a .tdms_index file for
the corresponding .tdms file. This index file enables LabVIEW to speed up random access to the
.tdms file. If you have limited disk space, wire a FALSE value to this input to prevent LabVIEW
from generating the .tdms_index file. The default is TRUE.

LabVIEW ignores this input if you open a .tdms file that already has a .tdms_index file.
Wiring a FALSE value to this input does not remove this file. LabVIEW might update this file
during the TDMS application to ensure this file is up-to-date. To remove this file, you can
manually delete it from the disk or programmatically delete it by using the Delete function.

Note If you use multiple TDMS Open functions, which have different values for the
create index file? input, to open the same .tdms file, LabVIEW uses the create index
file? input of the first TDMS Open function to determine whether to generate the
.tdms_index file or not. LabVIEW ignores the create index file? input of all
subsequent TDMS Open functions.

The .tdms_index file is optional in TDMS applications. When you distribute a TDMS
application or .tdms file to another computer, you do not need to include the corresponding
.tdms_index file. You can use this function to create a new .tdms_index file for your TDMS
application if necessary.

• file format version (2.0) —

1530 ni.com
 Functions

file format version specifies the file format version for the .tdms file.

Refer to the following support document at ni.com for more information about the .tdms file
format.

0 1.0
2.0
1
(default)

• file path —

file path specifies the absolute path to the file you want to open. If you use this function to
create a new file, the file extension of the filename you specify in file path must be .tdms.
Otherwise, this function automatically appends .tdms to the filename you specify. If you use
this function to open or update an existing file, you do not have to ensure that the file extension
is .tdms.

• operation (0:open) —

operation specifies the operation to perform.

0 open (default)—Opens a .tdms file to write to.

1 open or create—Creates a new .tdms file or opens an existing .tdms file to configure.
2 create or replace—Creates a new .tdms file or replaces an existing .tdms file.
3 create—Creates a new .tdms file.
4 open (read-only)—Opens a read-only version of the .tdms file.

• byte order (2:little-endian) —

byte order specifies the byte order, or endian format, of the data in the .tdms file. Byte order
specifies whether LabVIEW represents numeric values in memory from most significant byte to
least significant byte or vice versa.

The byte order input is valid only if you use this function to create a new .tdms file. If you use
this function to read an existing .tdms file, LabVIEW reads data in the byte order of that file and
represents the data in the native byte order of the host computer. If you use this function to
update an existing .tdms file, LabVIEW writes data in the byte order of that file.

big-endian, network order—Specifies that the most significant byte occupies the lowest
0
memory address.

© National Instruments 1531

 Functions

1 native, host order—Specifies that this function uses the byte order of the host computer.
little-endian (default)—Specifies that the least significant byte occupies the lowest memory
2
address.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• disable buffering? (T) —

disable buffering? (Windows) specifies whether LabVIEW opens, creates, or replaces a .tdms
file without system buffering. The default is TRUE, which means this function disables system
buffering and enables buffering in the TDMS disk cache.

Disabling system buffering can speed up data transfers in certain situations. If you have a small
amount of data to transfer, you might not notice a difference if you disable system buffering. To
read or write a data file to a Redundant Array of Independent Disks (RAID), consider opening the
file without system buffering to speed up data transfers. To read the same set of data repeatedly
from the computer, consider enabling system buffering.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Standard Read and Write\

TDMS Read Events Data.vi
• labview\examples\File IO\TDMS\Concurrent Access to TDMS
File.vi

1532 ni.com
 Functions

TDMS Write Function

Streams data to the specified .tdms file. The data subset to write is determined by the
values you identify in the group name in and channel name(s) in inputs.

Inputs/Outputs
• data layout (0:decimated) —

data layout specifies the arrangement of the data that you want to stream to a .tdms file. You
must use the same data layout for each channel under the same group.

decimated (default)—Specifies that the input data prioritizes channels before samples. This
arrangement first lists all samples from the first channel, then all samples from the second
channel, and so on through the last channel. The following table shows a typical example of
the

decimated
data layout.

0
Channel 0—Sample 1
Channel 0—Sample 2
...
Channel 0—Sample N
Channel 1—Sample 1
Channel 1—Sample 2
...

© National Instruments 1533

 Functions

Channel 1—Sample N
Channel 2—Sample 1
Channel 2—Sample 2
...
Channel 2—Sample N

interleaved—Specifies that the input data prioritizes samples before channels. This
arrangement lists the first sample from every channel, then the second sample from every
channel, and so on through the last sample from every channel. The following table shows a
typical example of the

interleaved
data layout.

Channel 0—Sample 1
1 Channel 1—Sample 1
Channel 2—Sample 1
Channel 0—Sample 2
Channel 1—Sample 2
Channel 2—Sample 2
...
Channel 0—Sample N
Channel 1—Sample N
Channel 2—Sample N

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• group name in (Untitled) —

group name in specifies the channel group on which to perform the operation. The default is
Untitled.

• channel name(s) in (Untitled) —

1534 ni.com
 Functions

channel name(s) in indicates the channels on which to perform the operation. If you do not wire
data to this input, LabVIEW names the channels automatically. If you wire waveform data to the
data input, LabVIEW uses waveform names. The data type that the channel name(s) in input
accepts can be a string or a 1D array of strings. The data type varies according to the data you
wire to the data input.

1D Array of
String String or 1D Array of Strings
Strings

1D array of: Digital waveform

• Signed or unsigned integers
• Floating-point numbers Digital table
• Timestamps
• Booleans 1D array of analog
waveforms

Analog Note
2D array of:
waveform
If data layout is decimated and you wire a 1D
• Signed or
1D array of array of strings to channel name(s) in, this VI uses
unsigned
alphanumeric the first element of the 1D array as the channel
integers
strings that do name.
• Floating-
not contain null point
If data layout is interleaved and you wire a string
characters numbers
to channel name(s) in, this VI uses this string as
the channel name of the first element in the 1D • Timestamps
array and uses Untitled, Untitled1, • Booleans
Untitled2...as the channel names of the rest • Alphanumeric
elements. strings that
do not
contain null
characters

If the data input contains compressed digital data, you must enter the name of the compression
channel as the first entry in the channel name(s) in array.

• data —

data is the data to write to the .tdms file.

This input accepts the following data types:

• Analog waveform or a 1D array of analog waveforms

• Digital waveform

© National Instruments 1535

 Functions

Caution When you write analog or digital waveforms to a new channel,

LabVIEW includes the timestamp information in the waveforms. However, when
you append analog or digital waveforms to an existing channel, LabVIEW might
discard the timestamp information in the new waveforms.

• Digital table
• Dynamic data
• 1D or 2D array of:
◦ Signed or unsigned integers
◦ Floating-point numbers, including the following specific data types:
▪ Single-precision and double-precision floating-point numbers
▪ Complex single-precision and double-precision floating-point numbers
▪ (Windows) Extended-precision floating-point numbers
◦ Timestamps
◦ Booleans
◦ Alphanumeric strings that do not contain null characters
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name(s) out —

channel name(s) out returns the channel name on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

1536 ni.com
 Functions

• labview\examples\File IO\TDMS\Standard Read and Write\

TDMS Write Events Data.vi
• labview\examples\File IO\TDMS\Standard Read and Write\
TDMS Write Time Domain Data.vi
• labview\examples\File IO\TDMS\Standard Read and Write\
TDMS Write Triggered Data.vi
• labview\examples\File IO\TDMS\Concurrent Access to TDMS
File.vi

TDMS Read Function

Reads the specified .tdms file and returns data in a format specified by the data type
input. If data has scaling information, this VI automatically scales the data. Use the
count and offset inputs to read a specified subset of the data.

Inputs/Outputs
• count (-1: all) —

count specifies the maximum number of data elements to read from the .tdms file for each
channel. The default is –1, all available elements.

• offset (0) —

offset specifies the number of data elements into the .tdms file at which the function begins
reading the .tdms file. The default is 0.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• group name in —

© National Instruments 1537

 Functions

group name in specifies the channel group on which to perform the operation.

If you do not wire data to this input, the following behavior occurs:

• LabVIEW reads data from the current group in the file. The current group is either the first
group in the file when you run this function for the first time or the nth group at the nth
cycle when you run this function continuously for multiple cycles.
• The order that the TDMS Read function reads groups is the same order that the TDMS List
Contents function returns groups.
• After LabVIEW reaches the last group, if the TDMS Read function attempts to run, LabVIEW
returns an end of file error.

Note The TDMS List Contents function and the TDMS Get Properties function will
reset the current group to the first group in the file. Resetting the current group to the
first group in the file impacts the group read by the next TDMS Read function when
you do not wire the group name in input.

• channel name(s) in —

channel name(s) in indicates the channel to perform the operation on. If you do not wire data to
this input, LabVIEW reads data from all channels under the same group. If you wire waveform
data to the data type input, LabVIEW uses waveform names. The data type that the channel
name(s) in input accepts can be a string or a 1D array of strings. The data type varies according
to the data you wire to the data type input.

String 1D Array of Strings

Digital waveform

Analog waveform Digital table

1D array of: 1D array of analog waveforms

• Signed or unsigned integers 2D array of:

• Floating-point numbers
• Timestamps • Signed or unsigned integers
• Booleans • Floating-point numbers
• Alphanumeric strings that do not contain • Timestamps
null characters • Booleans
• Alphanumeric strings that do not contain
null characters

1538 ni.com
 Functions

If you load a complete file or group that contains compressed digital data, LabVIEW
automatically inserts the compression channel name in the channel name(s) in array. If you load
a subset of a file or group that contains compressed digital data, you must enter the name of the
compression channel as the first entry in the channel name(s) in array.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type is the type of data that you want data to contain.

This input accepts the following data types:

• Analog waveform or a 1D array of analog waveforms
• Digital waveform
• Digital table
• Dynamic data
• 1D or 2D array of:
◦ Signed or unsigned integers
◦ Floating-point numbers, including the following specific data types:
▪ Single-precision and double-precision floating-point numbers
▪ Complex single-precision and double-precision floating-point numbers
▪ (Windows) Extended-precision floating-point numbers
◦ Timestamps
◦ Booleans
◦ Alphanumeric strings that do not contain null characters
• return channels in file order? (F) —

return channels in file order? specifies whether this function returns data channels in the same
order as they exist in the .tdms file. If the value is TRUE or if you do not specify the channel
name(s) in input, this function returns data channels in the same order as they exist in the
.tdms file. If the value is FALSE, this function returns data channels in the same order as you
specify in the channel name(s) in input. The default is FALSE.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

© National Instruments 1539

 Functions

group name out returns the name of the channel group on which you performed the operation.

• channel name(s) out —

channel name(s) out returns the channel name on which you performed the operation.

• data —

data contains the data read from the file in the specified data type. It can consist of any data
type depending on which data type you specify in data type and how count is set.

• error out —

error out contains error information. This output provides standard error out functionality.

• end of file? —

end of file? indicates if the end of the file has been reached.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Standard Read and Write\

TDMS Read Events Data.vi
• labview\examples\File IO\TDMS\Concurrent Access to TDMS
File.vi

TDMS Close Function

Closes the .tdms file you opened with the TDMS Open function.

Inputs/Outputs
• tdms file —

1540 ni.com
 Functions

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• file path out —

file path out returns the path of the .tdms file on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

(VxWorks) LabVIEW loads the shared TDMS component into memory when you open a
TDMS file. LabVIEW unloads this component from memory when you close all TDMS
files. On the VxWorks operating system, unloading the TDMS component from memory
will leak approximately 1.8 kilobytes of memory due to a known issue of VxWorks. You
can follow the guidelines below to avoid memory leak in your application.

• Avoid opening and closing TDMS files unnecessarily on VxWorks.

• Open an additional TDMS file at the beginning of the application and keep it open
until the application completes all TDMS reading and writing. This workaround will
keep the TDMS component in memory while you frequently open and close other
TDMS files.
• Set the TDMS component as a startup component on your RT target. To do this,
add tdms.out; to the StartupDLLs section of ni-rt.ini, which is located in
the root directory of your target (c:\ni-rt.ini), then restart the target. This
will prevent the TDMS component from being unloaded from memory when you
close TDMS files.

For information on how to access files such as ni-rt.ini on your RT target, refer to
the KnowledgeBase on ni.com.

© National Instruments 1541

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Standard Read and Write\

TDMS Read Events Data.vi
• labview\examples\File IO\TDMS\Concurrent Access to TDMS
File.vi

TDMS List Contents Function

Provides a list of group and channel names contained within the .tdms file specified in
the .tdms file input.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• group name —

group name indicates the channel group to analyze. If this input is not wired, the function
performs the operation on all channel and group names.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group names —

1542 ni.com
 Functions

group names lists the names of the channel groups in the specified .tdms file.

• group/channel names —

group/channel names lists the names of the channel groups and their associated channels in
the specified .tdms file.

If the group name input is wired, group/channel names returns the channel names within the
specified group.
• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Set Properties Function

Sets the properties of the specified .tdms file, channel group, or channel. If you wire
the group name and channel name inputs with values, the function writes the
properties at the channel level. Wiring only the group name input with a value writes
the properties at the channel group level. If both group name and channel name
inputs contain no values, the properties become file-specific. If you wire the channel
name input with a value, you must also wire a value to the group name input. You
must close the reference to the .tdms file or flush data to the .tdms file for changes to
take effect.

Inputs/Outputs
• property values —

property values specifies the property values of the specified channel group, channel, or .tdms
file. This input accepts the following data types:

• Signed or unsigned integers

• Floating-point numbers, including the following specific data types:

© National Instruments 1543

 Functions

◦ Single-precision and double-precision floating-point numbers

◦ Complex single-precision and double-precision floating-point numbers
◦ (Windows) Extended-precision floating-point numbers
• Timestamps
• Booleans
• Alphanumeric strings that do not contain null characters
• Variants that contain any of the data types specified above

If you want to set more than one property using the same function, you can wire a 1D array of
any of the previously specified data types to the property values input. Each value in the array
corresponds to a single property. However, a single property cannot hold an array of values.

• property names —

property names specifies the property names of the specified channel group, channel, or
.tdms file.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• group name —

group name specifies the channel group to perform the operation on. If you wire a value to the
channel name input, you must also wire a value to this input.

• channel name —

channel name specifies the channel to perform the operation on. If you wire a value to this
input, you must also wire a value to the group name input.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

1544 ni.com
 Functions

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

This section lists all properties that you might encounter when you use a .tdms file.
The first table lists all properties you might find in a .tdms file. The second table lists
all properties that do not exist in a .tdms file but which you can use to perform
certain actions. You can write these properties as waveform attributes to a .tdms file.
However, some of these properties might not appear as waveform attributes when you
read the waveform data from the .tdms file. The Available as a Waveform Attribute?
column provides information about whether a property is available as a waveform
attribute. If the data type of a property is not valid, LabVIEW treats the property as a
customized property and the property will not perform as described in the table.

You can use the TDMS Get Properties function to obtain the values of these properties.
Use the TDMS Set Properties function to change the values of these properties.

The following table lists all properties you might find in a .tdms file.

Available Available
in File as a
Property Name Data Type Access Description
Format Waveform
Versions Attribute?
Specifies the object name,
Read/ such as the root name, group
name String 2.0 Yes
write name, or channel name, in a
.tdms file.
Indicates the index of a
32-bit
column in a 2D array. This
signed Read 1.0 and
NI_ArrayColumn No property appears in a .tdms
integer only 2.0
file only if you write a 2D
numeric
array of data to the file.

© National Instruments 1545

 Functions

Available Available
in File as a
Property Name Data Type Access Description
Format Waveform
Versions Attribute?
64-bit
Represents the number of
unsigned Read 1.0 and
NI_ChannelLength Yes values in a channel of a
integer only 2.0
.tdms file.
numeric

Represents the data type of a

channel. The value is an
integer that corresponds to a
LabVIEW type code.

Note A .tdms file

uses a different
type code than
the LabVIEW type
code for the
following data
types:

• String: 0x20
16-bit • Boolean:
unsigned Read 1.0 and 0x21
NI_DataType Yes
integer only 2.0 • Time
numeric stamp:
0x44
• Fixed-point
number:
0x4F
• Single-
precision,
floating-
point
number
with units:
0x19
• Complex
single-

1546 ni.com
 Functions

Available Available
in File as a
Property Name Data Type Access Description
Format Waveform
Versions Attribute?

precision,
floating-
point
number:
0x08000c
• Complex
double-
precision,
floating-
point
number:
0x10000d
• DAQmx raw
data:
0xFFFFFFFF

For the full list of

TDMS data type
codes, refer to the
Data Type Values
section in TDMS
File Format
Internal Structure.

Indicates whether a digital

table is compressed or not. A
value of 1 indicates that the
Read 1.0 and
NI_DigitalCompression Boolean No digital table is compressed. If
only 2.0
the digital table is not
compressed, this property
does not appear.
32-bit
signed Read 1.0 and Indicates the index of a row
NI_DigitalLine No
integer only 2.0 in a digital table.
numeric

© National Instruments 1547

 Functions

Available Available
in File as a
Property Name Data Type Access Description
Format Waveform
Versions Attribute?
32-bit
signed Read 1.0 and Indicates the number of rows
NI_DigitalNumberOfLines No
integer only 2.0 in a digital table.
numeric
Specifies the number of
scales to use when you read
data from a .tdms file. For
example, if a .tdms file has
32-bit
five scales and you set the
unsigned Read/
NI_Number_Of_Scales 2.0 No value of
integer write
NI_Number_Of_Scales
numeric
to 4, LabVIEW applies only
the first four scales to the
data when you read the
.tdms file.
Specifies the scaling
information for the data in a
.tdms file. You can create
more than one scale in a
.tdms file.
NI_Scale[n]_config, where
n represents the order of the Read/ Note National
N/A 2.0 No
scale and config represents the write Instruments
configuration of the scale. recommends you
use the TDMS
Create Scaling
Information VI to
create scales.

Specifies whether LabVIEW

scales data when reading the
data from a .tdms file. If the
Read/
NI_Scaling_Status String 2.0 No value is unscaled and the
write
.tdms file contains one or
more scales, LabVIEW scales
the data. If the value is

1548 ni.com
 Functions

Available Available
in File as a
Property Name Data Type Access Description
Format Waveform
Versions Attribute?
scaled, LabVIEW does not
scale the data. For DAQmx
data channels, LabVIEW
cannot return unscaled data
even when
NI_Scaling_Status is
unscaled.
Read/ 1.0 and Specifies the unit of the
unit_string String No
write 2.0 channel data in a .tdms file.
Represents the increment
Read/ 1.0 and
wf_increment Double No between two consecutive
write 2.0
samples on the x-axis.
Represents the number of
32-bit samples in the first data
signed Read/ 1.0 and chunk of the waveform you
wf_samples No
integer write 2.0 write to a .tdms file. The
numeric value must be greater than
zero.
Frequency-domain data and
Read 1.0 and histogram results use this
wf_start_offset Double No
only 2.0 value as the first value on the
x-axis.
Represents the time at which
the waveform was acquired
or generated. This property
Read 1.0 and
wf_start_time Timestamp No can be zero if the time
only 2.0
information is relative or the
waveform is not in time
domain.
Indicates whether LabVIEW
Read 1.0 and interprets the x-axis data in
wf_time_pref String No
only 2.0 absolute time or relative
time.
wf_xname String Read 1.0 and No Indicates the name of the

© National Instruments 1549

 Functions

Available Available
in File as a
Property Name Data Type Access Description
Format Waveform
Versions Attribute?

only 2.0 x-axis of the waveform.

Read 1.0 and Indicates the unit text of the

wf_xunit_string String No
only 2.0 x-axis.

In addition to the properties in the table above, a .tdms file might also contain other
waveform attributes.

The following table lists all properties that do not exist in a .tdms file, but you can use
them to perform certain actions.

Available Available
Data in File as a
Property Name Unit Access Description
Type Format Waveform
Versions Attribute?
You can use the
NI_DiskCacheSize
improve the .tdms da
performance by alloca
amount of cache size i
the data. LabVIEW wri
data in bytes per file. T
is valid only when the
32-bit buffering? input of the
unsigned Read/ function is TRUE. The
NI_DiskCacheSize Byte 2.0 Yes
integer write for this property is app
numeric MB. Wire a different va
property values input
Set Properties functio
the cache size. A great
the NI_DiskCacheS
property usually can im
writing performance; h
greater value also requ
computer resources.

1550 ni.com
 Functions

Available Available
Data in File as a
Property Name Unit Access Description
Type Format Waveform
Versions Attribute?
You can use the
NI_DiskGapSize p
improve the .tdms da
performance when rea
discontinuous data. Th
valid only when the di
buffering? input of the
function is TRUE. The
NI_DiskGapSize p
multiple of the sector
local hard disk. The de
for this property is 10.
gap in the .tdms file i
the value of the
NI_DiskGapSize p
TDMS Read function c
data from the file at on
32-bit data gap in the .tdms
unsigned Read/ than the value of the
NI_DiskGapSize Byte 2.0 Yes
integer write NI_DiskGapSize p
numeric TDMS Read function re
piece of data one at a
function finishes readi
Wire a value to the pro
input of the TDMS Set
function to change the

Note Obtain
optimal read
writing perfo
trial-and-err
The same co
might not re
same optima
performance
different com
might need t

© National Instruments 1551

 Functions

Available Available
Data in File as a
Property Name Unit Access Description
Type Format Waveform
Versions Attribute?

property valu
deploy an ap
from one com
another.

64-bit You can use the

signed Read NI_InMemoryFileS
NI_InMemoryFileSize Byte 2.0 Yes
integer only property to return the
numeric .tdms file in memory
You can use the
NI_InMemoryWrite
property to allocate th
in memory for writing
default value for this p
MB. The value range fo
64-bit property is [1 KB, 1 GB
signed Read/ value for this property
NI_InMemoryWriteBlockSize Byte 2.0 Yes
integer write improve the in-memo
numeric performance by alloca
blocks; however, a gre
also requires more com
resources. You must se
property before the w
begins. Otherwise, Lab
an error.
You can use the
NI_MinimumBuffer
property to improve th
data writing performa
32-bit
to a file less often. This
unsigned Data Read/ 1.0 and
NI_MinimumBufferSize Yes reduce the size of a .t
integer sample write 2.0
controlling the numbe
numeric
data is written to disk.
NI_MinimumBuffer
property is valid only i
layout input of the TD

1552 ni.com
 Functions

Available Available
Data in File as a
Property Name Unit Access Description
Type Format Waveform
Versions Attribute?
function is decimated
the value of the
NI_MinimumBuffer
property is zero. If you
at the group level, this
sets the value of unde
channels whose value
set the value at the file
function also sets the
underlying groups and
whose value is zero. U
property and the
NI_DiskCacheSize
affects file buffering w
You can use the TDMS
Properties function to
groups and channels i
files. Wire
NI_UpdateGroupNa
property names input
to rename a group and
NI_UpdateChannel
property names input
NI_UpdateChannelName
Write 1.0 and to rename a channel. W
String N/A Yes
only 2.0 group or channel nam
NI_UpdateGroupName
property values input
group or channel nam
want to replace to the
or channel name inpu
groups or channels yo
group name or chann
not exist, LabVIEW cre
groups or channels wi
names.

© National Instruments 1553

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Standard Read and Write\

TDMS Write Time Domain Data.vi

TDMS Get Properties Function

Returns the properties of the specified .tdms file, channel group, or channel. If you
wire the group name and channel name inputs with values, the function searches for
properties at the channel level. Wiring only the group name input with a value
searches for properties at the channel group level. If both group name and channel
name inputs contain no values, the function searches for properties at the root level of
the .tdms file. If you wire the channel name input with a value, you must also wire a
value to the group name input.

Inputs/Outputs
• data type —

data type controls the data type of the property values or property value output.

This input accepts the following data types:

Data Type Default Value

Signed or unsigned integer 0
Single-precision or double-precision floating-point number 0
Complex single-precision or double-precision floating-point number 0+0i
(Windows) Extended-precision floating-point number 0
Alphanumeric string that does not contain null characters Empty string

1554 ni.com
 Functions

Data Type Default Value

Timestamp 00:00:00.000
Boolean FALSE
Variant that contains any of the data types specified above Empty variant

To return more than one property using the same function, you can wire a 1D array of any of the
previously specified data types to the data type input. Each value in the array corresponds to a
single property. However, a single property cannot hold an array of values.

• property name —

property name specifies the name of the property whose values you want to get. If you do not
wire this input, this function returns the property names and their property values for the
specified group name, channel name, or the entire .tdms file. If you wire this input, the
property value output replaces property values and returns the value of the specified property;
the found output replaces property names and returns TRUE. If the specified property does not
exist in the .tdms file, the property value output returns the default value of the specified data
type and the found output returns FALSE.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• group name —

group name specifies the channel group to perform the operation on. If you wire a value to the
channel name input, you must also wire a value to this input.

• channel name —

channel name specifies the channel to perform the operation on. If you wire a value to this
input, you must also wire a value to the group name input.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

© National Instruments 1555

 Functions

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• property values —

property values returns the property values of the specified channel group, channel, or .tdms
file. This output is available only if the property name input is not wired.

The data type of this parameter is determined by the data type input.
• property value —

property value replaces the property values output and returns the property value of the
specified property. This output is available only if the property name input is wired.

The data type of this parameter is determined by the data type input.
• property names —

property names returns the property names of the specified channel group, channel, or .tdms
file. This output is available only if the property name input is not wired.

• found — found replaces the property names output and indicates whether the specified
property exists in the .tdms file or not. This output is available only if the property name input
is wired.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Concurrent Access to TDMS

File.vi

TDMS Flush Function

Writes all buffers of the .tdms file data to the file identified by the tdms file input. Data

1556 ni.com
 Functions

written to a .tdms file often resides in a buffer until the buffer fills up or until you close
the file. This function forces the operating system to write any buffer data to the .tdms
file.

Note Flushing data too frequently might negatively impact the writing
performance of your application.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Flush Written TDMS Data.vi

© National Instruments 1557

 Functions

TDMS File Viewer

Opens the .tdms file specified in the file in input and presents the file data in the TDMS
File Viewer dialog box.

Inputs/Outputs
• file in —

file in is the absolute path to the file you want to open.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• file out —

file out returns file in unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Standard Read and Write\

TDMS Write Events Data.vi
• labview\examples\File IO\TDMS\Standard Read and Write\
TDMS Write Triggered Data.vi

TDMS Defragment Function

Defragments the .tdms file data specified in the file path input. Use this function to

1558 ni.com
 Functions

clean up your .tdms data when it becomes cluttered, and increase performance.

Inputs/Outputs
• file path —

file path is the path to the .tdms file you want to defragment.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Advanced TDMS

Use the Advanced TDMS VIs and functions to perform advanced file I/O operations,
such as asynchronous reads and writes, on .tdms files. You can use these VIs and
functions to read data from an existing .tdms file, write data to a new .tdms file, or
replace subsets of data in an existing .tdms file. You also can use these VIs and
functions to convert the file format version of a .tdms file or to create scaling
information for unscaled data.

Note Use the standard TDMS VIs and functions when the features of the
Advanced TDMS VIs and functions are not necessary. Incorrect use of the
Advanced TDMS VIs and functions might result in a corrupt .tdms file. If you
disable buffering when using the Advanced TDMS VIs and functions, the data
size you read or write must be a multiple of the sector size of the hard disk.

The VIs and functions on this palette can return TDM streaming error codes.

© National Instruments 1559

 Functions

Palette
Description
Object
Opens a .tdms file for reading or writing in the byte order of the host computer. You
TDMS
also can use this function to create a new file or replace an existing file. Unlike the
Advanced
TDMS Open function, the TDMS Advanced Open function does not create a
Open
.tdms_index file. If you use this function to open an existing .tdms file that has a
Function
corresponding .tdms_index file, this function removes the .tdms_index file.
TDMS
Advanced Closes the .tdms file that you opened with the TDMS Advanced Open function and
Close releases extra disk space that the TDMS Reserve File Size function reserves.
Function
TDMS Set
Defines the channel information of the raw data that you want to write to the
Channel
specified .tdms file. The channel information includes the data layout, name of the
Information
group, names of the channels, data type, and number of samples.
Function

Creates scaling information for unscaled data in a .tdms file. This VI writes the
scaling information to the .tdms file. You must manually select the polymorphic
TDMS Create
instance to use.
Scaling
Information
To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

TDMS Delete
Deletes data from a channel or multiple channels in a group.
Data Function
TDMS Set
Configures the offset at which the TDMS Advanced Asynchronous Write or TDMS
Next Write
Advanced Synchronous Write function starts overwriting the existing data in a .tdms
Position
file.
Function
TDMS Set
Next Read Configures the offset at which the TDMS Advanced Asynchronous Read function
Position starts reading data from a .tdms file.
Function
TDMS Reserve Pre-allocates disk space for writing and prevents fragmentation on a file-system
File Size level. If you are running this function on Windows with User Account Control

1560 ni.com
 Functions

Palette
Description
Object
enabled, you must run LabVIEW or the application with administrator privileges to
Function
avoid a run-time error.

Converts the file format version of a .tdms file from 1.0 to 2.0 or vice versa. This VI
TDMS Convert overwrites the .tdms file with the new file format version you specify in the target
Format version input. This VI also changes the byte order of the .tdms file to native, host
order.

TDMS
Advanced Use the TDMS Advanced Synchronous I/O functions to synchronously read data
Synchronous from or write data to .tdms files.
I/O
TDMS
Advanced Use the TDMS Advanced Asynchronous I/O functions to asynchronously read data
Asynchronous from or write data to .tdms files.
I/O

Use the TDMS Advanced Data Reference I/O functions to interact with data that is
owned by a component external to LabVIEW, such as the direct memory access
TDMS
(DMA) buffer of a device driver that controls a data-streaming device. You can use
Advanced
these functions to asynchronously write data from the DMA buffer of a device driver
Data
to .tdms files without needing to copy the data into a LabVIEW array first. You also
Reference I/O
can use these functions to asynchronously read data from .tdms files and place the
data directly into the DMA buffer.

TDMS In Use the TDMS In Memory functions to open, close, read from, and write to .tdms
Memory files in memory.

TDMS Advanced Open Function

Opens a .tdms file for reading or writing in the byte order of the host computer. You
also can use this function to create a new file or replace an existing file. Unlike the
TDMS Open function, the TDMS Advanced Open function does not create a
.tdms_index file. If you use this function to open an existing .tdms file that has a

© National Instruments 1561

 Functions

corresponding .tdms_index file, this function removes the .tdms_index file.

Inputs/Outputs
• file path —

file path specifies the absolute path to the file you want to open. If you use this function to
create a new file, the file extension of the filename you specify in file path must be .tdms.
Otherwise, this function automatically appends .tdms to the filename you specify. If you use
this function to open or update an existing file, you do not have to ensure that the file extension
is .tdms.

• operation (0:open) —

operation specifies the operation to perform.

0 open (default)—Opens a .tdms file to write to.

1 open or create—Creates a new .tdms file or opens an existing .tdms file to configure.
2 create or replace—Creates a new .tdms file or replaces an existing .tdms file.
3 create—Creates a new .tdms file.
4 open (read-only)—Opens a read-only version of the .tdms file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• disable buffering? (T) —

disable buffering? (Windows) specifies whether LabVIEW opens, creates, or replaces a .tdms
file without system buffering. The default is TRUE, which means this function disables system
buffering. If the value is TRUE, the size of data to read or write must be a multiple of the sector
size of the hard disk.

Disabling system buffering can speed up data transfers in certain situations. If you have a small
amount of data to transfer, you might not notice a difference if you disable buffering. To read or

1562 ni.com
 Functions

write a data file to a Redundant Array of Independent Disks (RAID), consider opening the file
without buffering to speed up data transfers. To read the same set of data repeatedly from the
computer, consider enabling buffering.

• enable asynchronous? (T) —

enable asynchronous? (Windows) specifies whether to enable asynchronous reads or writes for
the .tdms file. Set the value to TRUE if you want to use the TDMS Advanced Asynchronous I/O
or TDMS Advanced Data Reference I/O functions. Set the value to FALSE if you want to use the
TDMS Advanced Synchronous I/O functions. The default is TRUE.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• sector size —

sector size returns the sector size of the hard disk. (macOS/Linux/RT targets) sector size is not
supported and returns a value of zero.

Note Traditionally, the sector size of hard disks is 512 bytes. In recent years, the
sector size is 4096 bytes for large hard disks and RAID arrays.

• error out —

error out contains error information. This output provides standard error out functionality.

The byte order, or endian format, specifies whether LabVIEW represents numeric
values in memory from most significant byte to least significant byte or vice versa.

Note Use this function to open a .tdms file with a file format version of 2.0.
To open a version 1.0 file, use the TDMS Open function.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

© National Instruments 1563

 Functions

Asynchronous Read and Write\TDMS Advanced Asynchronous

Write.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Basic
Asynchronous Read.vi

TDMS Advanced Close Function

Closes the .tdms file that you opened with the TDMS Advanced Open function and
releases extra disk space that the TDMS Reserve File Size function reserves.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• truncate file? (F) —

truncate file? specifies whether to truncate the .tdms file when closing this file. If the value is
TRUE, this function truncates the file at the current writing position. If the value is FALSE, this
function does not truncate the file and only releases extra disk space that the TDMS Reserve File
Size function reserves. The default is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (10 s) —

timeout specifies the maximum time, in seconds, that this function waits for pending
asynchronous writes to complete before closing the .tdms file. If you do not wire data to the
timeout input, this function sets the value to 10. This input is valid only if the enable

1564 ni.com
 Functions

asynchronous? input of the TDMS Advanced Open function is TRUE.

• file path out —

file path out returns the path of the .tdms file on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Asynchronous
Write.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Basic
Asynchronous Read.vi

TDMS Set Channel Information Function

Defines the channel information of the raw data that you want to write to the specified
.tdms file. The channel information includes the data layout, name of the group,
names of the channels, data type, and number of samples.

Note If you use this function multiple times in an application, the order in
which you use this function determines the order of channels and groups
that you write to a .tdms file.

© National Instruments 1565

 Functions

Inputs/Outputs
• data layout (0:non-interleaved) —

data layout specifies the arrangement of the data that you want to stream to a .tdms file. You
must use the same data layout for each channel under the same group.

non-interleaved (default)—Specifies that the input data prioritizes channels before samples.
This arrangement first lists all samples from the first channel, then all samples from the second
channel, and so on through the last channel. The following table shows a typical example of
the non-interleaved data layout.

Channel 0—Sample 1
Channel 0—Sample 2
...
0 Channel 0—Sample N
Channel 1—Sample 1
Channel 1—Sample 2
...
Channel 1—Sample N
Channel 2—Sample 1
Channel 2—Sample 2
...
Channel 2—Sample N

interleaved—Specifies that the input data prioritizes samples before channels. This
arrangement lists the first sample from every channel, then the second sample from every
1
channel, and so on through the last sample from every channel. The following table shows a
typical example of the interleaved data layout.

1566 ni.com
 Functions

Channel 0—Sample 1
Channel 1—Sample 1
Channel 2—Sample 1
Channel 0—Sample 2
Channel 1—Sample 2
Channel 2—Sample 2
...
Channel 0—Sample N
Channel 1—Sample N
Channel 2—Sample N

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• group name (Untitled) —

group name specifies the group name for the channel. If you do not wire data to this input or if
you wire an empty string to this input, this function uses Untitled as the group name.

• channel name(s) —

channel name(s) specifies the names for the channels.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type specifies the type of data on which you want to perform the operation. This input
accepts integers, floating-point numbers, Booleans, and timestamps.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• (Windows) Extended-precision floating-point numbers

© National Instruments 1567

 Functions

• samples per channel —

samples per channel specifies the number of data samples that each channel contains.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

The following use cases demonstrate how the TDMS Set Channel Information function
arranges raw data according to the data layout input.

Single Group, Single Channel (Non-Interleaved)

The data layout in the file is consecutive samples per channel. In the previous figure, a
single 16-bit numeric or I16 sample follows another I16 sample, which follows another
I16 sample, and so on. You can write as many I16 samples as you want. For example,
you can write one million I16 samples or two million I16 samples at a time.

Single Group, Multiple Channels (Non-Interleaved)

1568 ni.com
 Functions

The data layout is 8 consecutive samples per channel. In the previous figure, the data
layout is eight I16 samples for the ch0 channel, eight I16 samples for the ch1 channel,
and so on.

Single Group, Multiple Channels (Interleaved)

In the previous figure, the data layout is an I16 sample for the ch0 channel followed by
an I16 sample for the ch1 channel. This pair repeats in the file. The total file size or the
NI_ChannelLength property determines how often the pair repeats.

Multiple Group, Multiple Channels (Non-Interleaved)

The data layout is 8 consecutive samples per channel per group or device. In the
previous figure, the data layout contains eight I16 samples for the ch0 channel for
device1, eight I16 samples for the ch1 channel for device1, eight I16 samples for
the ch0 channel for device2, eight I16 samples for the ch1 channel for device2,
and so on.

© National Instruments 1569

 Functions

Multiple Group, Multiple Channels (Interleaved)

In the previous figure, the data layout is 8 pairs of an I16 sample for the ch0 channel
and an I16 sample for the ch1 channel of device1. Following the 8 pairs is 8 pairs of
an I16 sample for the ch0 channel and an I16 sample for the ch1 channel of
device2. This pattern repeats in the file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Append Multiple
Headers.vi

TDMS Create Scaling Information

Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

1570 ni.com
 Functions

• TDMS Create Scaling Information (Linear) VI

• TDMS Create Scaling Information (Polynomial) VI
• TDMS Create Scaling Information (Thermocouple) VI
• TDMS Create Scaling Information (RTD) VI
• TDMS Create Scaling Information (Table) VI
• TDMS Create Scaling Information (Strain) VI
• TDMS Create Scaling Information (Thermistor) VI
• TDMS Create Scaling Information (Reciprocal) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Create Scaling Information (Linear) VI

Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

© National Instruments 1571

 Functions

Inputs/Outputs
• linear scale —

linear scale specifies the linear scaling information. A linear scale uses the equation y=mx+b,
where x is a pre-scaled value, and y is a scaled value.

• slope —

slope specifies the slope, or m in the equation, for the scale. The default is 0.

• y intercept —

y intercept specifies the y intercept, or b in the equation, for the scale. The default is 0.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

1572 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Create Scaling Information

(Polynomial) VI
Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel

© National Instruments 1573

 Functions

Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

Inputs/Outputs
• polynomial scale —

polynomial scale specifies the polynomial scaling information. A polynomial scale uses an nth-
order polynomial equation.

• coefficients —

coefficients specifies the coefficients for the scale that converts pre-scaled values to scaled
values. Each element of the array corresponds to a term of the equation.

For example, if index three of the array is 9, the fourth term of the equation is 9x3.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

1574 ni.com
 Functions

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

© National Instruments 1575

 Functions

TDMS Create Scaling Information

(Thermocouple) VI
Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

Inputs/Outputs
• thermocouple scale —

thermocouple scale specifies the thermocouple scaling information, which scales the .tdms
data from microvolts to degrees Celsius.

If the data is not in microvolts, first convert the data to microvolts with an additional scale. For
example, you can use the TDMS Create Scaling Information (Linear) instance VI to convert the
data.

• thermocouple type —

thermocouple type specifies the type of thermocouple connected to the channel.

Thermocouple types differ in composition and measurement range.

1576 ni.com
 Functions

10047 B—Specifies the B-type thermocouple.

10055 E—Specifies the E-type thermocouple.
10072 J (default)—Specifies the J-type thermocouple.
10073 K—Specifies the K-type thermocouple.
10077 N—Specifies the N-type thermocouple.
10082 R—Specifies the R-type thermocouple.
10085 S—Specifies the S-type thermocouple.
10086 T—Specifies the T-type thermocouple.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

© National Instruments 1577

 Functions

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Create Scaling Information (RTD) VI

Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

1578 ni.com
 Functions

Inputs/Outputs
• RTD scale —

RTD scale specifies the resistance temperature detector (RTD) scaling information, which scales
the .tdms data in degrees Celsius.

• current excitation —

current excitation specifies, in amperes, the amount of excitation that the sensor requires.
Refer to the sensor documentation to determine this value.

• r0 nominal resistance —

r0 nominal resistance specifies the sensor resistance, in ohms, at 0 degrees Celsius. The
Callendar-Van Dusen equation requires this value. Refer to the sensor documentation to
determine this value.

• a—

a specifies the a coefficient for the Callendar-Van Dusen equation. Refer to the sensor
documentation to determine this value.

• b—

b specifies the b coefficient for the Callendar-Van Dusen equation. Refer to the sensor
documentation to determine this value.

• c—

c specifies the c coefficient for the Callendar-Van Dusen equation. Refer to the sensor
documentation to determine this value.

• lead wire resistance —

© National Instruments 1579

 Functions

lead wire resistance specifies the amount of resistance in ohms in the lead wires. Ideally,
this value is the same for all leads.

• resistance configuration —

resistance configuration specifies the number of wires to use for resistance measurements.

2 2-Wire (default)—Specifies the 2-wire mode.

3 3-Wire—Specifies the 3-wire mode.
4 4-Wire—Specifies the 4-wire mode.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

1580 ni.com
 Functions

standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Create Scaling Information (Table) VI

Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

© National Instruments 1581

 Functions

Note This VI does not scale strings or complex floating-point numbers.

Inputs/Outputs
• table scale —

table scale specifies the table scaling information. A table scale maps an array of pre-scaled
values to an array of corresponding scaled values.

• scaled values —

scaled values specifies the scaled values that map to the values in pre-scaled values.

• pre-scaled values —

pre-scaled values specifies the pre-scaled values that map to the values in scaled values.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over

1582 ni.com
 Functions

tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

© National Instruments 1583

 Functions

TDMS Create Scaling Information (Strain) VI

Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

Inputs/Outputs
• strain scale —

strain scale specifies the strain scaling information, which scales the .tdms data in strains.
Strain is the amount of deformation of a body due to an applied force. Specifically, strain is the
fractional change in length.

• configuration —

configuration specifies the bridge configuration for the strain gages.

10183 Full Bridge I (default)

10184 Full Bridge II
10185 Full Bridge III
10188 Half Bridge I
10189 Half Bridge II

1584 ni.com
 Functions

10271 Quarter Bridge I

10272 Quarter Bridge II

• Poisson ratio —

Poisson ratio specifies the ratio of lateral strain to axial strain in the material you are
measuring.

• gage resistance —

gage resistance specifies the resistance, in ohms, of the gages in an unstrained position.
Each gage in the bridge must have the same nominal gage resistance. The resistance across
arms of the bridge that do not have strain gages also must be the same as the nominal gage
resistance. Refer to the sensor documentation to determine this value.

• lead wire resistance —

lead wire resistance specifies the amount of resistance in ohms in the lead wires. Ideally,
this value is the same for all leads.

• initial bridge voltage —

initial bridge voltage specifies in volts the output voltage of the bridge in the unloaded
condition. This VI subtracts this value from any measurements before applying scaling
equations. Perform a voltage measurement on the bridge with no strain applied to
determine this value.

• gage factor —

gage factor specifies the sensitivity of the strain gages and relates the change in electrical
resistance to the change in strain. Each gage in the bridge must have the same gage factor.
Refer to the sensor documentation to determine this value.

• voltage excitation —

voltage excitation specifies in volts the amount of excitation that the sensor requires. Refer
to the sensor documentation to determine this value.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can

© National Instruments 1585

 Functions

wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

1586 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Create Scaling Information

(Thermistor) VI
Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

© National Instruments 1587

 Functions

Inputs/Outputs
• thermistor scale —

thermistor scale specifies the thermistor scaling information, which scales the .tdms data in
Kelvin.

• resistance configuration —

resistance configuration specifies the number of wires to use for resistance measurements.

2 2-Wire (default)—Specifies the 2-wire mode.

3 3-Wire—Specifies the 3-wire mode.
4 4-Wire—Specifies the 4-wire mode.

• excitation type —

excitation type specifies the type of excitation for the scale.

10122 Voltage (default)—Voltage excitation.

10334 Current—Current excitation.

• excitation value —

excitation value specifies the amount of excitation that the sensor requires. When
excitation type is Current, the unit of excitation value is amperes. When excitation type is
Voltage, the unit of excitation value is volts. Refer to the sensor documentation to
determine this value.

• r1 reference resistance —

r1 reference resistance specifies, in ohms, the value of the reference resistor.

• lead wire resistance —

lead wire resistance specifies the amount of resistance in ohms in the lead wires. Ideally,
this value is the same for all leads.

• a—

a specifies the a constant for the Steinhart-Hart thermistor equation. Refer to the sensor

1588 ni.com
 Functions

documentation to determine the value for this constant.

• b—

b specifies the b constant for the Steinhart-Hart thermistor equation. Refer to the sensor
documentation to determine the value for this constant.

• c—

c specifies the c constant for the Steinhart-Hart thermistor equation. Refer to the sensor
documentation to determine the value for this constant.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over
group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

© National Instruments 1589

 Functions

standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Create Scaling Information

(Reciprocal) VI
Creates scaling information for unscaled data in a .tdms file. This VI writes the scaling
information to the .tdms file. You must manually select the polymorphic instance to
use.

To call this VI with TDMS Advanced functions, only call the TDMS Set Channel
Information function after any calls to this VI.

1590 ni.com
 Functions

Use the TDMS File Viewer VI to retrieve the scaling information from a .tdms file.

Note This VI does not scale strings or complex floating-point numbers.

Inputs/Outputs
• reciprocal scale —

reciprocal scale specifies the reciprocal scaling information. A reciprocal scale divides the
number 1 by an input value. If the input value is zero, this VI uses zero as the reciprocal.

• input source —

input source specifies the ID of the child scale. If the current scale has a child scale, you can
wire the scale ID of the child scale to this input. The default is –1, which specifies that the
current scale does not have a child scale.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Open function to open the refnum. group name and channel name take precedence
over this input. If you specify a value for either group name or channel name, this VI applies the
scaling information to either the group or the channel, respectively. If you do not specify a value
for them, this VI applies the scaling information to the .tdms data.

• group name —

group name specifies the group name for the .tdms data. This input takes precedence over
tdms file but has a lower priority than channel name.

• channel name —

channel name specifies the channel name for the .tdms data. This input takes precedence over

© National Instruments 1591

 Functions

group name and tdms file. If you do not specify a value for channel name, this VI applies the
scaling information to the group. If you do not specify a value for group name either, this VI
applies the scaling information to the .tdms data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• group name out —

group name out returns the name of the channel group on which you performed the operation.

• channel name out —

channel name out returns the name of the channel on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

• scale ID —

scale ID returns the ID of the resulting scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Scale TDMS Data.vi

TDMS Delete Data Function

Deletes data from a channel or multiple channels in a group.

1592 ni.com
 Functions

Note This function does not support digital data or DAQmx raw data.

Inputs/Outputs
• count (-1: all) —

count specifies the number of data samples to delete from the .tdms file for each channel. The
default is -1, which means this function deletes all data samples from the position you specify in
from.

If the value of count is out of range for a channel, this function automatically sets count to the
number of data samples in that channel.

• from (0: start) —

from specifies from where to delete data samples from the .tdms file for each channel.

0 start (default)—Specifies to delete data samples from the beginning of each channel.
1 end—Specifies to delete data samples from the end of each channel.

• file path —

file path is the absolute path to the file you want to open.

• group name in —

group name in specifies the channel group on which to perform the operation.

• channel name(s) in —

channel name(s) in specifies the channel to perform the operation on. If you do not wire data to
this input, LabVIEW performs the operation on all channels under the same group.

• error in (no error) —

© National Instruments 1593

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• keep empty group/channel? (T) —

keep empty group/channel? specifies whether to keep the group or channels in the .tdms file
if the group or channels are empty after this function deletes data samples. The default is TRUE,
which means this function keeps the empty group or channels.

• file path out —

file path out returns the path of the .tdms file on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

When the data you wire contains waveform data, LabVIEW sets the following channel
properties and waveform attributes:

• If the waveform attribute NI_ExpXDimension represents time or if this attribute

does not exist, LabVIEW sets the following values:
◦ wf_start_offset = wf_start_offset + count * wf_increment
◦ If the waveform attribute NI_ExpTimeStamp exists, LabVIEW sets
NI_ExpTimeStamp = NI_ExpTimeStamp + count * 1/wf_increment
• If the waveform attribute NI_ExpXDimension represents frequency, LabVIEW
sets the following values:
◦ wf_start_offset = wf_start_offset + count * 1/wf_increment
◦ If the waveform attribute NI_ExpTimeStamp exists, LabVIEW sets
NI_ExpTimeStamp = NI_ExpTimeStamp + count * 1/wf_increment
• After this function deletes data, if the number of data samples in the .tdms file is
less than the value of the channel property wf_samples, LabVIEW sets the value
of wf_samples to equal the number of data samples in the .tdms file.

Examples

Refer to the following example files included with LabVIEW.

1594 ni.com
 Functions

• labview\examples\File IO\TDMS\TDMS Delete Data from

Channels.vi

TDMS Set Next Write Position Function

Configures the offset at which the TDMS Advanced Asynchronous Write or TDMS
Advanced Synchronous Write function starts overwriting the existing data in a .tdms
file.

Note Overwriting existing data from the middle of a file might result in a
corrupt final file. National Instruments recommends that you truncate the file
when you finish writing, or make sure you overwrite the entire remainder of
the file. Use the truncate file? input of the TDMS Advanced Close function to
truncate a .tdms file.

Inputs/Outputs
• channel name in —

channel name in specifies the channel on which to perform the operation.

• group name in —

group name in specifies the group on which to perform the operation.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• offset (0) —

© National Instruments 1595

 Functions

offset specifies how far in the raw data from the location specified by from to set the file
position. The default is 0. If the disable buffering? input of the TDMS Advanced Open function is
TRUE, the next write position you set must be a multiple of the sector size of the hard disk.

• from (0:start) —

from specifies where to set the file position in the raw data based on the offset.

start (default)—Sets the file position offset samples from the beginning of the raw data in the
0 .tdms file. If the value of from is 0, the value of offset must be equal to or greater than 0,
which sets the file position at the beginning of the raw data.
end—Sets the file position offset samples from the end of the raw data in the .tdms file. If the
1 value of from is 1, the value of offset must be equal to or less than 0, which sets the file
position at the end of the raw data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Overwrite.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Ring Buffer.vi

1596 ni.com
 Functions

TDMS Set Next Read Position Function

Configures the offset at which the TDMS Advanced Asynchronous Read function starts
reading data from a .tdms file.

Inputs/Outputs
• channel name in —

channel name in specifies the channel on which to perform the operation.

• group name in —

group name in specifies the group on which to perform the operation.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• offset (0) —

offset specifies how far in the raw data from the location specified by from to set the file
position. The default is 0. If the disable buffering? input of the TDMS Advanced Open function is
TRUE, the next read position you set must be a multiple of the sector size of the hard disk.

• from (0: start) —

from specifies where to set the file position in the raw data based on the offset.

start (default)—Sets the file position offset samples from the beginning of the raw data in the
0 .tdms file. If the value of from is 0, the value of offset must be equal to or greater than 0,
which sets the file position at the beginning of the raw data.
1 end—Sets the file position offset samples from the end of the raw data in the .tdms file. If the

© National Instruments 1597

 Functions

value of from is 1, the value of offset must be equal to or less than 0, which sets the file
position at the end of the raw data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Finite
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Prefetched
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Synchronous Read and Write\TDMS Advanced Synchronous
Read.vi

TDMS Reserve File Size Function

Pre-allocates disk space for writing and prevents fragmentation on a file-system level.
If you are running this function on Windows with User Account Control enabled, you
must run LabVIEW or the application with administrator privileges to avoid a run-time
error.

1598 ni.com
 Functions

Note

If you are using this function to build an application, National Instruments

recommends that you embed an application manifest to the application. The
requested execution level in the manifest file must be
requireAdministrator.

When a .tdms file is in use by this function, no other processes can access this
file.

Inputs/Outputs
• append? (T) —

append? specifies whether to append the new size that this function reserves to an existing file.
If the value is FALSE, this function changes the file size of tdms file to the reserved size. If the
value is TRUE, this function extends the file size of tdms file with the reserved size. The default is
TRUE.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• reserve size —

reserve size specifies the size to reserve in samples.

You can calculate the actual size, in bytes, that this function reserves by multiplying the value of
reserve size by the number of bytes of data type. For example, if the value of reserve size is 512
and data type is an unsigned 16-bit integer, then you can calculate the actual size that this
function reserves as follows: 512×(16÷8) = 1024 bytes.

For large files of several terabytes, the operating system may take a significant amount of time to

© National Instruments 1599

 Functions

pre-allocate disk space. Insert a delay in your application after the TDMS Reserve File Size
function to ensure the file size is fully reserved. For multiple files on separate RAID volumes, if
you reserve the file size in a loop, insert a single delay after the loop to avoid serializing the
delays. NI recommends a time delay of 500 ms/TB.

Note If the disable buffering? input of the TDMS Advanced Open function is TRUE,
the actual reserved size in bytes must be a multiple of the sector size of the hard disk.
Use the TDMS Advanced Open function to obtain the sector size of the hard disk.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type specifies the type of data on which you want to perform the operation. This input
accepts integers, floating-point numbers, Booleans, and timestamps.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• Extended-precision floating-point numbers

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Append Multiple
Headers.vi

1600 ni.com
 Functions

TDMS Convert Format

Converts the file format version of a .tdms file from 1.0 to 2.0 or vice versa. This VI
overwrites the .tdms file with the new file format version you specify in the target
version input. This VI also changes the byte order of the .tdms file to native, host
order.

Inputs/Outputs
• file path —

file path specifies the path to the .tdms file you want to convert.

• target version —

target version specifies the file format version to which you want to convert the .tdms file.

0 1.0
1 2.0

• new property name —

new property name specifies a new name for the name property of a group or channel in the
.tdms file. For example, if a group has a name property with a value TDMSDataGroup, and if
you wire a value group name to this input and run this VI, the original name property of this
group changes to group name, which has a value TDMSDataGroup. This VI creates a new
name property for this group, and uses the group name that you specified when creating this
.tdms file as the property value. This input is valid only when target version is 2.0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• file path out —

© National Instruments 1601

 Functions

file path out returns the path of the .tdms file on which you performed the operation.

• error out —

error out contains error information. This output provides standard error out functionality.

When converting a .tdms file from file format version 1.0 to 2.0, this VI makes the
following changes to the properties of the .tdms file.

• If the .tdms file does not have a name property, this VI adds a name property for
this file and uses the filename as the value of the name property.
• If the groups or channels of the .tdms file have name properties, this VI keeps the
property values in the version 2.0 file. However, this VI changes the object paths of
these groups and channels. For example, if you use the TDMS Write function to
write .tdms data to a version 1.0 file without wiring a value to the group name in
input, the TDMS Write function automatically names the group as Untitled.
Even if you later use the TDMS Set Properties function to create a name property
for this group and assign a different value than Untitled, you still need to access
this group from Untitled. You cannot access this group from the new name
property value. However, if you use the TDMS Convert Format VI to convert this
.tdms file to version 2.0, you no longer can access this group from Untitled.
You must access this group from the name property value that you specified
earlier.

Tip To access groups or channels from the original names that you
specified for version 1.0, wire a value to the new property name input to
change the name property to a new property name.

• If the name property of the groups or channels has duplicate values, this VI
appends a numeric suffix to the duplicate values. For example, if a .tdms file has a
group of three channels with the same channel name TDMSDataChannel, this VI
changes the values of the name property in the second and third groups to
TDMSDataChannel 1 and TDMSDataChannel 2, respectively. This VI does
not change the property value of the first channel and keeps the value as
TDMSDataChannel.

1602 ni.com
 Functions

TDMS Advanced Synchronous I/O

Use the TDMS Advanced Synchronous I/O functions to synchronously read data from
or write data to .tdms files.

Palette Object Description

TDMS Advanced Synchronous
Writes data to the specified .tdms file synchronously.
Write Function
TDMS Advanced Synchronous Reads the specified .tdms file and returns data in a format
Read Function specified by the data type input.

TDMS Advanced Synchronous Write

Function
Writes data to the specified .tdms file synchronously.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• data —

data specifies the data to write to the .tdms file. This input accepts a 1D or 2D array of integers,
floating-point numbers, Booleans, and timestamps. If the disable buffering? input of the TDMS
Advanced Open function is TRUE, the size of data must be a multiple of the sector size and the

© National Instruments 1603

 Functions

array size must be less than 67,076,096 bytes on x86 systems, 67,051,520 bytes on IA-64 systems,
or 33,525,760 bytes on x64 systems.

Refer to the Microsoft Developer Network Web site at msdn.microsoft.com for more
information about calculating the maximum array size.

Note

You can wire the following floating-point numbers to this input:

• Single-precision and double-precision floating-point numbers

• Complex single-precision and double-precision floating-point numbers
• (Windows) Extended-precision floating-point numbers

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Synchronous Read and Write\TDMS Advanced Synchronous
Write.vi

TDMS Advanced Synchronous Read Function

Reads the specified .tdms file and returns data in a format specified by the data type

1604 ni.com
 Functions

input.

Inputs/Outputs
• count (-1) —

count specifies the maximum number of data elements you want to read. The default is -1,
which specifies that this function reads all data elements. If the disable buffering? input of the
TDMS Advanced Open function is TRUE, the value of (count * the length of data type) must be a
multiple of the sector size.

You can calculate the size, in bytes, that this function reads by multiplying the value of count by
the number of bytes of data type. For example, if the value of count is 512 and data type is an
unsigned 16-bit integer, then you can calculate the size that this function reads as follows:
512×(16÷8) = 1024 bytes.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type specifies the type of data on which you want to perform the operation. This input
accepts integers, floating-point numbers, Booleans, and timestamps.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• (Windows) Extended-precision floating-point numbers

• tdms file out —

© National Instruments 1605

 Functions

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• data —

data returns the data this function reads from the .tdms file in the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

• read process finished? —

read process finished? indicates whether the reading process finished or not.

Tip Use this Boolean value as one of the stop conditions for a While Loop. For
example, you can put the TDMS Advanced Synchronous Read function in the While
Loop to read data infinitely until the value of read process finished? becomes TRUE.
This value becomes TRUE when the TDMS Advanced Synchronous Read function
reaches the end of a .tdms file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Synchronous Read and Write\TDMS Advanced Synchronous
Read.vi

TDMS Advanced Asynchronous I/O

Use the TDMS Advanced Asynchronous I/O functions to asynchronously read data from
or write data to .tdms files.

Note To use the TDMS Advanced Asynchronous I/O functions, you must set
the enable asynchronous? input of the TDMS Advanced Open function to
TRUE.

1606 ni.com
 Functions

Palette
Description
Object
TDMS
Allocates buffers and configures the timeout value for asynchronous writes. The
Configure
timeout value applies to all subsequent asynchronous writes. You must use this
Asynchronous
function to configure the asynchronous writes before using the TDMS Advanced
Writes
Asynchronous Write function.
Function
TDMS
Writes data to the specified .tdms file asynchronously. This function can initiate
Advanced
multiple asynchronous writes that take place in the background. You can use the
Asynchronous
TDMS Get Asynchronous Write Status function to query the number of pending
Write
asynchronous writes.
Function
TDMS Get
Asynchronous Retrieves the number of pending asynchronous writes issued by the TDMS
Write Status Advanced Asynchronous Write function.
Function

Generates random data that you can use to test the performance of the Advanced
TDMS
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the
Generate
production of data from a data acquisition device. Wire data to the data type input
Random Data
to determine the polymorphic instance to use or manually select the instance.

TDMS
Allocates buffers and configures the timeout value for asynchronous reads. The
Configure
timeout value applies to all subsequent asynchronous reads. You must use this
Asynchronous
function to configure the asynchronous reads before using the TDMS Advanced
Reads
Asynchronous Read function.
Function
TDMS Start Starts an asynchronous read process. You cannot configure or start an
Asynchronous asynchronous read process unless the previous process has completed or stopped.
Reads You can stop an asynchronous read process by using the TDMS Stop Asynchronous
Function Reads function.
TDMS Stop Stops issuing new asynchronous reads. This function does not discard completed
Asynchronous asynchronous reads or cancel pending asynchronous reads. After you use this
Reads function to stop asynchronous reads, you still can use the TDMS Advanced
Function Asynchronous Read function to read the completed asynchronous reads.

© National Instruments 1607

 Functions

Palette
Description
Object
TDMS Get
Asynchronous Retrieves the number of buffers that contain data available for the TDMS Advanced
Read Status Asynchronous Read function to read.
Function
TDMS
Reads the specified .tdms file and returns data in a format specified by the data
Advanced
type input. This function returns data that was previously read into the buffers
Asynchronous
configured in the TDMS Configure Asynchronous Reads function. This function can
Read
execute multiple asynchronous reads simultaneously in the background.
Function

TDMS Configure Asynchronous Writes

Function
Allocates buffers and configures the timeout value for asynchronous writes. The
timeout value applies to all subsequent asynchronous writes. You must use this
function to configure the asynchronous writes before using the TDMS Advanced
Asynchronous Write function.

Inputs/Outputs
• max write size —

max write size specifies the maximum size, in samples, to allocate for each asynchronous write.
This input is valid only if pre-allocate? is TRUE.

You can calculate the actual maximum size, in bytes, that this function pre-allocates by
multiplying the value of max write size by the number of bytes of data type. For example, if the
value of max write size is 512 and data type is an unsigned 16-bit integer, then you can calculate

1608 ni.com
 Functions

the actual maximum size that this function pre-allocates as follows: 512×(16÷8) = 1024 bytes.

Note If the disable buffering? input of the TDMS Advanced Open function is TRUE,
the actual maximum size in bytes must be a multiple of the sector size of the hard
disk. Use the TDMS Advanced Open function to obtain the sector size of the hard disk.

• pre-allocate? (F) —

pre-allocate? specifies whether to pre-allocate buffers to return to LabVIEW in exchange for the
data buffers you pass to the TDMS Advanced Asynchronous Write function. The default is FALSE.

Set the value to TRUE to avoid run-time buffer allocations. If pre-allocate? is TRUE, you must
wire a supported data type to this function.

• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• max asynchronous writes (4) —

max asynchronous writes specifies the maximum number of asynchronous writes that can run
simultaneously in the background. After the number of pending asynchronous writes reaches
the maximum value, the TDMS Advanced Asynchronous Write function waits for a pending
asynchronous write to complete before issuing another asynchronous write. The value must be
greater than zero. The default is 4.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type specifies the data type of the pre-allocated buffers. These pre-allocated buffers are
returned to LabVIEW in exchange for the data buffers you pass to the TDMS Advanced
Asynchronous Write function. This input accepts integers, floating-point numbers, Booleans,
and timestamps. You must wire a supported data type to this input if pre-allocate? is TRUE.
LabVIEW ignores this input if pre-allocate? is FALSE.

• timeout (5 s) —

© National Instruments 1609

 Functions

timeout specifies the timeout value, in seconds, for the TDMS Advanced Asynchronous Write
function. When the number of pending asynchronous writes reaches the maximum value, the
TDMS Advanced Asynchronous Write function waits as long as the timeout value for a pending
asynchronous write to complete before issuing another asynchronous write. If you do not wire
data to this input, this function sets the value to 5.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Append Multiple
Headers.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Asynchronous
Write.vi

TDMS Advanced Asynchronous Write

Function
Writes data to the specified .tdms file asynchronously. This function can initiate
multiple asynchronous writes that take place in the background. You can use the TDMS
Get Asynchronous Write Status function to query the number of pending
asynchronous writes.

1610 ni.com
 Functions

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• data —

data specifies the data to write to the .tdms file. This input accepts a 1D or 2D array of integers,
floating-point numbers, Booleans, and timestamps. If the disable buffering? input of the TDMS
Advanced Open function is TRUE, the size of data must be a multiple of the sector size and the
array size must be less than 67,076,096 bytes on x86 systems, 67,051,520 bytes on IA-64 systems,
or 33,525,760 bytes on x64 systems.

Refer to the Microsoft Developer Network Web site at msdn.microsoft.com for more
information about calculating the maximum array size.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• Extended-precision floating-point numbers

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1611

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Asynchronous
Write.vi

TDMS Get Asynchronous Write Status

Function
Retrieves the number of pending asynchronous writes issued by the TDMS Advanced
Asynchronous Write function.

Tip Use this function when you monitor an application that issues a series of
asynchronous writes over a long period of time. By querying the number of
pending writes and keeping track of the highest value this function returns,
you can choose an appropriate value for the max asynchronous writes input
of the TDMS Configure Asynchronous Writes function.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

1612 ni.com
 Functions

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• number of pending writes —

number of pending writes returns the number of pending asynchronous writes issued by the
TDMS Advanced Asynchronous Write function.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Ring Buffer.vi

TDMS Generate Random Data

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

• TDMS Generate Random Data (U8) VI

• TDMS Generate Random Data (I8) VI
• TDMS Generate Random Data (U16) VI
• TDMS Generate Random Data (I16) VI
• TDMS Generate Random Data (U32) VI
• TDMS Generate Random Data (I32) VI
• TDMS Generate Random Data (U64) VI
• TDMS Generate Random Data (I64) VI

© National Instruments 1613

 Functions

• TDMS Generate Random Data (SGL) VI

• TDMS Generate Random Data (DBL) VI
• TDMS Generate Random Data (CSG) VI
• TDMS Generate Random Data (CDB) VI

TDMS Generate Random Data (U8) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

1614 ni.com
 Functions

TDMS Generate Random Data (I8) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (U16) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine

© National Instruments 1615

 Functions

the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (I16) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

1616 ni.com
 Functions

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (U32) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

© National Instruments 1617

 Functions

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (I32) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

1618 ni.com
 Functions

standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (U64) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

© National Instruments 1619

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (I64) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

1620 ni.com
 Functions

TDMS Generate Random Data (SGL) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (DBL) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine

© National Instruments 1621

 Functions

the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (CSG) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

1622 ni.com
 Functions

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Generate Random Data (CDB) VI

Generates random data that you can use to test the performance of the Advanced
TDMS VIs and functions. Use this VI in benchmarking tests to simulate the production
of data from a data acquisition device. Wire data to the data type input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• data type —

data type specifies the data type of the random data you want to generate.

• number of samples —

© National Instruments 1623

 Functions

number of samples specifies the number of data samples you want to generate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data returns the random data with the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Configure Asynchronous Reads

Function
Allocates buffers and configures the timeout value for asynchronous reads. The
timeout value applies to all subsequent asynchronous reads. You must use this
function to configure the asynchronous reads before using the TDMS Advanced
Asynchronous Read function.

Note Before using this function, ensure that no asynchronous reads are
pending.

Inputs/Outputs
• tdms file —

1624 ni.com
 Functions

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• number of buffers (4) —

number of buffers specifies the number of buffers to allocate for asynchronous reads. The value
must be greater than zero. The default is 4.

• buffer size —

buffer size specifies the buffer size in samples of data. If the disable buffering? input of the
TDMS Advanced Open function is TRUE, the value of (buffer size * the length of data type) must
be a multiple of the sector size.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type specifies the type of data on which you want to perform the operation. This input
accepts integers, floating-point numbers, Booleans, and timestamps.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• Extended-precision floating-point numbers

• timeout (5 s) —

timeout specifies the timeout value, in seconds, for the asynchronous read. If you do not wire
data to this input, this function sets the value to 5.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1625

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Basic
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Prefetched
Asynchronous Read.vi

TDMS Start Asynchronous Reads Function

Starts an asynchronous read process. You cannot configure or start an asynchronous
read process unless the previous process has completed or stopped. You can stop an
asynchronous read process by using the TDMS Stop Asynchronous Reads function.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• total count (-1) —

total count specifies the total number of values of the data type you want to read from a .tdms
file. The default is –1, which specifies that LabVIEW keeps initiating asynchronous reads until this
function reaches the end of the .tdms file or you stop initiating asynchronous reads by using
the TDMS Stop Asynchronous Reads function.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

1626 ni.com
 Functions

standard error in functionality.

• data type —

data type specifies the type of data on which you want to perform the operation. This input
accepts integers, floating-point numbers, Booleans, and timestamps.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• Extended-precision floating-point numbers

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Basic
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Prefetched
Asynchronous Read.vi

TDMS Stop Asynchronous Reads Function

Stops issuing new asynchronous reads. This function does not discard completed
asynchronous reads or cancel pending asynchronous reads. After you use this function
to stop asynchronous reads, you still can use the TDMS Advanced Asynchronous Read

© National Instruments 1627

 Functions

function to read the completed asynchronous reads.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Prefetched
Asynchronous Read.vi

1628 ni.com
 Functions

TDMS Get Asynchronous Read Status

Function
Retrieves the number of buffers that contain data available for the TDMS Advanced
Asynchronous Read function to read.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• number of buffers available —

number of buffers available returns the number of buffers that contain data for the TDMS
Advanced Asynchronous Read function to read.

• all buffers full? —

all buffers full? indicates whether all the buffers are full of data for the TDMS Advanced
Asynchronous Read function to read.

This output also can be TRUE even when the number of buffers available output of this function
is not equal to the number of buffers input of the TDMS Configure Asynchronous Reads function
under the following conditions:

© National Instruments 1629

 Functions

• The TDMS Advanced Asynchronous Read function reaches the end of a .tdms file.
• The TDMS Advanced Asynchronous Read function finishes reading the total count of data
that you specify in the TDMS Start Asynchronous Reads function.

Tip Use this Boolean value as one of the stop conditions for a While Loop. For
example, you can put the TDMS Get Asynchronous Read Status function in the While
Loop and wire the all buffers full? output to the Stop if True conditional terminal of
the While Loop. You then can start asynchronous reads by using the TDMS Start
Asynchronous Reads function and wait for the all buffers full? value to become TRUE.
When this value becomes TRUE, you can use the TDMS Advanced Asynchronous Read
function to read the data from the buffers.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Finite
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Prefetched
Asynchronous Read.vi

TDMS Advanced Asynchronous Read

Function
Reads the specified .tdms file and returns data in a format specified by the data type
input. This function returns data that was previously read into the buffers configured
in the TDMS Configure Asynchronous Reads function. This function can execute
multiple asynchronous reads simultaneously in the background.

1630 ni.com
 Functions

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data type —

data type specifies the type of data on which you want to perform the operation. This input
accepts integers, floating-point numbers, Booleans, and timestamps.

Note You can wire the following floating-point numbers to this input:
• Single-precision and double-precision floating-point numbers
• Complex single-precision and double-precision floating-point numbers
• Extended-precision floating-point numbers

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• data —

data returns the data this function reads from the .tdms file in the specified data type.

• error out —

error out contains error information. This output provides standard error out functionality.

• read process finished? —

read process finished? indicates whether the reading process is finished or not.

© National Instruments 1631

 Functions

Tip

Use this Boolean value as one of the stop conditions for a While Loop. For example,
you can place the TDMS Advanced Asynchronous Read function in the While Loop to
read data indefinitely until the value of read process finished? returns TRUE. This
value returns TRUE when one of the following conditions occurs:

• The TDMS Advanced Asynchronous Read function reaches the end of a .tdms
file.
• The TDMS Advanced Asynchronous Read function finishes reading total count
of data that you specify for the TDMS Start Asynchronous Reads function.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

Asynchronous Read and Write\TDMS Advanced Basic
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Finite
Asynchronous Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\
Asynchronous Read and Write\TDMS Advanced Prefetched
Asynchronous Read.vi

TDMS Advanced Data Reference I/O

Use the TDMS Advanced Data Reference I/O functions to interact with data that is
owned by a component external to LabVIEW, such as the direct memory access (DMA)
buffer of a device driver that controls a data-streaming device. You can use these
functions to asynchronously write data from the DMA buffer of a device driver to .tdms
files without needing to copy the data into a LabVIEW array first. You also can use these
functions to asynchronously read data from .tdms files and place the data directly into
the DMA buffer.

1632 ni.com
 Functions

Note To use the TDMS Advanced Data Reference I/O functions, you must set
the enable asynchronous? input of the TDMS Advanced Open function to
TRUE.

Palette
Description
Object
TDMS
Configures the maximum number of asynchronous writes and the timeout value.
Configure
The timeout value applies to all subsequent asynchronous writes. You must use
Asynchronous
this function to configure the asynchronous writes before using the TDMS Advanced
Writes (Data
Asynchronous Write (Data Ref) function.
Ref) Function
TDMS
Writes data referenced by the data reference input to the specified .tdms file
Advanced
asynchronously. The data reference input typically refers to a portion of data
Asynchronous
owned by a component external to LabVIEW, such as a region of a DMA buffer that
Write (Data
contains data you want to write to the .tdms file.
Ref) Function
TDMS Get
Asynchronous
Returns the number of pending asynchronous writes issued by the TDMS Advanced
Write Status
Asynchronous Write (Data Ref) function.
(Data Ref)
Function
TDMS Configures the maximum number of asynchronous reads, total amount of data to
Configure read, and the timeout value for the asynchronous reads. The timeout value applies
Asynchronous to all subsequent asynchronous reads. You must use this function to configure the
Reads (Data asynchronous reads before using the TDMS Advanced Asynchronous Read (Data
Ref) Function Ref) function.
TDMS
Reads data from the specified .tdms file asynchronously and stores the data in the
Advanced
memory of a component external to LabVIEW. Use the data reference input of this
Asynchronous
function to specify the location of the external memory, such as a region of a DMA
Read (Data
buffer owned by a device driver.
Ref) Function
TDMS Get
Returns the number of pending asynchronous reads issued by the TDMS Advanced
Asynchronous
Asynchronous Read (Data Ref) function.
Read Status

© National Instruments 1633

 Functions

Palette
Description
Object
(Data Ref)
Function

TDMS Configure Asynchronous Writes (Data

Ref) Function
Configures the maximum number of asynchronous writes and the timeout value. The
timeout value applies to all subsequent asynchronous writes. You must use this
function to configure the asynchronous writes before using the TDMS Advanced
Asynchronous Write (Data Ref) function.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• max asynchronous writes (4) —

max asynchronous writes specifies the maximum number of asynchronous writes that can run
simultaneously in the background. After the number of pending asynchronous writes reaches
the maximum value, the TDMS Advanced Asynchronous Write (Data Ref) function waits for a
pending asynchronous write to complete before issuing another asynchronous write. The value
must be greater than zero. The default is 4.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (5 s) —

1634 ni.com
 Functions

timeout specifies the timeout value, in seconds, for the TDMS Advanced Asynchronous Write
(Data Ref) function. When the number of pending asynchronous writes reaches the maximum
value, the TDMS Advanced Asynchronous Write (Data Ref) function waits as long as the timeout
value for a pending asynchronous write to complete before issuing another asynchronous write.
If you do not wire data to this input, this function sets the value to 5.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Advanced Asynchronous Write (Data

Ref) Function
Writes data referenced by the data reference input to the specified .tdms file
asynchronously. The data reference input typically refers to a portion of data owned
by a component external to LabVIEW, such as a region of a DMA buffer that contains
data you want to write to the .tdms file.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• data reference —

© National Instruments 1635

 Functions

data reference specifies the external data value reference that points to the external data you
want to write to the .tdms file. This input accepts an external data value reference containing a
1D or 2D array of integers, floating-point numbers, Booleans, or timestamps. If the disable
buffering? input of the TDMS Advanced Open function is TRUE, the size of data that you wire to
the data reference input must be a multiple of the sector size.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• auto delete reference? (T) —

auto delete reference? specifies whether you want LabVIEW to delete the data reference
automatically after the asynchronous operation completes. Deleting the data reference notifies
the owner of the external memory that LabVIEW no longer needs access to the external memory.
The default is TRUE. Set this value to FALSE when you want to continue using the reference after
the asynchronous operation completes. For example, you might want to modify the data in
LabVIEW before deleting the reference. If you set the value to FALSE, you must use the Delete
Data Value Reference function to delete the data reference.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

This function can issue additional asynchronous writes while executing previously-
issued asynchronous writes in the background. When the number of asynchronous
writes in the background reaches the maximum value, this function waits until a
previously-issued asynchronous write completes before issuing an additional
asynchronous write. If the previously-issued asynchronous write does not complete
within the timeout value, this function returns error code –2546. Use the TDMS
Configure Asynchronous Writes (Data Ref) function to configure the maximum number
of asynchronous writes and the timeout value.

Use the TDMS Get Asynchronous Write Status (Data Ref) function to query the number
of pending asynchronous writes.

1636 ni.com
 Functions

TDMS Get Asynchronous Write Status (Data

Ref) Function
Returns the number of pending asynchronous writes issued by the TDMS Advanced
Asynchronous Write (Data Ref) function.

Tip Use this function when you monitor an application that issues a series of
asynchronous writes over a long period of time. By querying the number of
pending writes and keeping track of the highest value this function returns,
you can choose an appropriate value for the max asynchronous writes input
of the TDMS Configure Asynchronous Writes (Data Ref) function.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• number of pending writes —

number of pending writes returns the number of asynchronous writes that have not completed.
You can use this information to monitor a write-to-disk operation.

© National Instruments 1637

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Configure Asynchronous Reads (Data

Ref) Function
Configures the maximum number of asynchronous reads, total amount of data to read,
and the timeout value for the asynchronous reads. The timeout value applies to all
subsequent asynchronous reads. You must use this function to configure the
asynchronous reads before using the TDMS Advanced Asynchronous Read (Data Ref)
function.

Note Before using this function, ensure that no asynchronous reads are
pending.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• max asynchronous reads (4) —

max asynchronous reads specifies the maximum number of asynchronous reads that can run
simultaneously in the background. After the number of pending asynchronous reads reaches the
maximum value, the TDMS Advanced Asynchronous Read (Data Ref) function waits for a pending
asynchronous read to complete before issuing another asynchronous read. The value must be
greater than zero. The default is 4.

1638 ni.com
 Functions

• total size (in bytes) (-1) —

total size specifies the total size, in bytes, of the data to read from the .tdms file. The default is
–1, which specifies that the TDMS Advanced Asynchronous Read (Data Ref) function keeps
issuing asynchronous reads until this function reaches the end of the .tdms file. Use this input
in conjunction with the read process finished? output of the TDMS Advanced Asynchronous
Read (Data Ref) function to control an asynchronous reading process.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (5 s) —

timeout specifies the timeout value, in seconds, for the TDMS Advanced Asynchronous Read
(Data Ref) function. When the number of pending asynchronous reads reaches the maximum
value, the TDMS Advanced Asynchronous Read (Data Ref) function waits as long as the timeout
value for a pending asynchronous read to complete before issuing another asynchronous read. If
you do not wire data to this input, this function sets the value to 5.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS Advanced Asynchronous Read (Data

Ref) Function
Reads data from the specified .tdms file asynchronously and stores the data in the
memory of a component external to LabVIEW. Use the data reference input of this
function to specify the location of the external memory, such as a region of a DMA
buffer owned by a device driver.

© National Instruments 1639

 Functions

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• data reference —

data reference specifies the external data value reference that points to the region of an external
buffer in which you want LabVIEW to store the data this function reads from the .tdms file. This
input accepts an external data value reference containing a 1D or 2D array of integers, floating-
point numbers, Booleans, or timestamps. If the disable buffering? input of the TDMS Advanced
Open function is TRUE, the size of data that you wire to the data reference input must be a
multiple of the sector size.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• auto delete reference? (T) —

auto delete reference? specifies whether you want LabVIEW to delete the data reference
automatically after the asynchronous operation completes. Deleting the data reference notifies
the owner of the external memory that LabVIEW no longer needs access to the external memory.
The default is TRUE. Set this value to FALSE when you want to continue using the reference after
the asynchronous operation completes. For example, you might want to modify the data in
LabVIEW before deleting the reference. If you set the value to FALSE, you must use the Delete
Data Value Reference function to delete the data reference.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

1640 ni.com
 Functions

• read process finished? —

read process finished? indicates whether the reading process is finished or not.

Tip Use this Boolean value as one of the stop conditions for a While Loop. For
example, you can place the TDMS Advanced Asynchronous Read (Data Ref) function
in the While Loop to read data indefinitely until the value of read process finished?
returns TRUE. This value returns TRUE when one of the following conditions occurs:
• The TDMS Advanced Asynchronous Read (Data Ref) function reaches the end
of a .tdms file.
• The TDMS Advanced Asynchronous Read (Data Ref) function finishes reading
the total size of data that you specify for the TDMS Configure Asynchronous
Reads (Data Ref) function.

This function can issue additional asynchronous reads while executing previously-
issued asynchronous reads in the background. When the number of asynchronous
reads in the background reaches the maximum value, this function waits until a
previously-issued asynchronous read completes before issuing an additional
asynchronous read. If the previously-issued asynchronous read does not complete
within the timeout value, this function returns error code –2546. Use the TDMS
Configure Asynchronous Reads (Data Ref) function to configure the maximum number
of asynchronous reads and the timeout value.

Use the TDMS Get Asynchronous Read Status (Data Ref) function to query the number
of pending asynchronous reads.

TDMS Get Asynchronous Read Status (Data

Ref) Function
Returns the number of pending asynchronous reads issued by the TDMS Advanced
Asynchronous Read (Data Ref) function.

Tip Use this function when you monitor an application that issues a series of
asynchronous reads over a long period of time. By querying the number of
pending reads and keeping track of the highest value this function returns,

© National Instruments 1641

 Functions

you can choose an appropriate value for the max asynchronous reads input
of the TDMS Configure Asynchronous Reads (Data Ref) function.

Inputs/Outputs
• tdms file —

tdms file specifies a reference number to the .tdms file on which to perform the operation. Use
the TDMS Advanced Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• number of pending reads —

number of pending reads returns the number of asynchronous reads that have not completed.
You can use this information to monitor a read-from-disk operation.

• error out —

error out contains error information. This output provides standard error out functionality.

TDMS In Memory
Use the TDMS In Memory functions to open, close, read from, and write to .tdms files in
memory.

1642 ni.com
 Functions

Palette Object Description

TDMS In Memory Creates an empty .tdms file in memory for reading or writing. You also can use
Open Function this function to create a file in memory from a byte array or file on disk.
TDMS In Memory
Reads a .tdms file in memory and returns data as an unsigned 8-bit integer array
Read Bytes
data type.
Function
Closes the .tdms file in memory that you opened with the TDMS In Memory Open
TDMS In Memory
function. This function also writes the .tdms file to disk, if specified by the file
Close Function
path input.

TDMS In Memory Open Function

Creates an empty .tdms file in memory for reading or writing. You also can use this
function to create a file in memory from a byte array or file on disk.

Use the TDMS In Memory Close function to close the reference to this file.

Inputs/Outputs
• byte array or file path —

byte array or file path specifies the byte array or file path from which to create a .tdms file in
memory. The byte order of the byte array or file on disk, if specified, determines the byte order
of the .tdms file in memory this function creates.

If you do not specify byte array or file path, this function creates an empty .tdms file in
memory that uses the byte order of the host computer.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

© National Instruments 1643

 Functions

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

TDMS In Memory Write and Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\In
Memory Network Read and Write\TDMS In Memory Network Read
and Write.lvproj

TDMS In Memory Read Bytes Function

Reads a .tdms file in memory and returns data as an unsigned 8-bit integer array data
type.

Inputs/Outputs
• byte count (-1: all) —

byte count specifies the maximum number of bytes to read from the .tdms file in memory. The
default is -1, which means this function reads all available bytes.

If the value of byte count is out of range, this function automatically sets byte count to equal the
number of bytes in the file minus offset.
• offset (0) —

1644 ni.com
 Functions

offset specifies the number of bytes into the .tdms file at which the function begins reading the
.tdms file. The default is 0.

• tdms file —

tdms file specifies a reference number to the .tdms file in memory on which to perform the
operation. Use the TDMS In Memory Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• tdms file out —

tdms file out returns a TDMS file reference to the .tdms file on which you performed the
operation.

• data —

data returns the data read from the .tdms file in memory as an unsigned 8-bit integer array
data type.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\TDMS\Advanced Read and Write\

TDMS In Memory Write and Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\In
Memory Network Read and Write\TDMS In Memory Network Read
and Write.lvproj

© National Instruments 1645

 Functions

TDMS In Memory Close Function

Closes the .tdms file in memory that you opened with the TDMS In Memory Open
function. This function also writes the .tdms file to disk, if specified by the file path
input.

Inputs/Outputs
• overwrite (F) —

overwrite specifies whether to overwrite the file you specify in file path with the .tdms file in
memory. The default is FALSE, which means that this VI does not overwrite the file.

• file path —

file path specifies the absolute path to the file on disk that you want to write the .tdms file in
memory.

• tdms file —

tdms file specifies a reference number to the .tdms file in memory on which to perform the
operation. Use the TDMS In Memory Open function to open the refnum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

1646 ni.com
 Functions

• labview\examples\File IO\TDMS\Advanced Read and Write\

TDMS In Memory Write and Read.vi
• labview\examples\File IO\TDMS\Advanced Read and Write\In
Memory Network Read and Write\TDMS In Memory Network Read
and Write.lvproj

Storage/DataPlugin

Use the Storage/DataPlugin VIs to read measurement data from a variety of file
formats, write data to .tdm or .tdms files, or manage DataPlugins installed on the local
computer. You must download appropriate DataPlugins and register them on the local
computer before you can access the corresponding file formats. Refer to the National
Instruments website at ni.com/dataplugins to download DataPlugins.

Note If you build an installer for a stand-alone application or shared library

that uses the Storage/DataPlugin VIs, you must include the NI USI installer. To
include the NI USI installer, on the Additional Installers page of the Installer
Properties dialog box, remove the checkmark from the Automatically select
recommended installers checkbox and place a checkmark in the NI USI
checkbox.

The VIs on this palette can return storage error codes.

Palette
Description
Object
Opens an NI TDM (.tdm) file for reading or writing. You also can use this VI to create a
Open Data
new file or replace an existing file. Use the Close Data Storage VI to close the reference
Storage
to the file.
Adds a channel group or channel to a file you specify. You also can use this VI to
Write Data
define properties for the channel group or channel that you want to add.
Returns an array of refnums that represent channel groups or channels in the file. If
Read Data you select Channel as the Object type to read in the configuration dialog box, this VI
reads waveforms associated with the channel. You also can use this VI to return

© National Instruments 1647

 Functions

Palette
Description
Object
channel groups or channels that meet query conditions you specify.

Closes a data file. You must use this Express VI to close a data file after you finish
Close Data
reading from or writing to the file. Memory leakage might occur if you do not close the
Storage
data file.

Defines the properties of an existing file, channel group, or channel. If you configure
this VI before you wire a refnum to storage refnum, the configuration might change
Set
depending on the refnum you wire. For example, if you configure this VI for a channel
Properties
and then wire a channel group refnum, the VI returns broken wires on the block
diagram because the same properties are not available for a channel group.
Reads property values from a file, channel group, or channel. If you configure this VI
before you wire a refnum to storage refnum, the configuration might change
Get
depending on the refnum you wire. For example, if you configure this VI for a channel
Properties
and then wire a channel group refnum, the VI returns broken wires on the block
diagram because the same properties are not available for a channel group.

Removes a channel group or channel you specify. If you choose to delete a channel
group, this VI deletes all channels associated with that channel group. Wire data to
Delete Data
the storage refnum input to determine the polymorphic instance to use or manually
select the instance.

Data File Opens the data file specified in the file path input and presents the data in the Data
Viewer File Viewer dialog box.

Convert to
TDM or Converts the specified file to the .tdm or .tdms file format.
TDMS

Manage Use the Manage DataPlugins VIs to list, export, register, or unregister DataPlugins
DataPlugins installed on the local computer.

Advanced Use the Advanced Storage VIs to read, write, and query data when object types or
Storage property names are determined at run time.

1648 ni.com
 Functions

Open Data Storage

Opens an NI TDM (.tdm) file for reading or writing. You also can use this VI to create a
new file or replace an existing file. Use the Close Data Storage VI to close the reference
to the file.

Note You must download appropriate DataPlugins and register them on the
local computer before you can access the corresponding data files. Refer to
the National Instruments website at ni.com/dataplugins to download
DataPlugins.

Dialog Box Options

Option Description

Specifies the format of the file you want to access. If you wire a value to the
DataPlugin name block diagram input of this Express VI, LabVIEW ignores the
DataPlugin option. If you wire an empty string to the DataPlugin name block
diagram input, LabVIEW automatically detects the storage format of the data file.

Contains the following options:

• auto-detect the storage format—Automatically detects the storage format of the

DataPlugin data file you specify in the File location option or the file path block diagram
input.
• TDM Streaming (high performance)—Opens or replaces an existing .tdms file or
creates a new .tdms file. This storage format has a higher performance
compared to the TDM with XML Header storage format.
• TDM with XML Header (medium performance)—Opens or replaces an existing
.tdm file or creates a new .tdm file.
• CSV—Opens an existing data file with comma-separated values (CSV).
• DAT—Opens an existing .dat file.

© National Instruments 1649

 Functions

Option Description

• LVM—Opens an existing text-based measurement file (.lvm).

Tip Click the Install/Update DataPlugins button on this dialog box to

download more DataPlugins from ni.com and install more storage
formats to this list.

Contains the following option:

DataPlugin
parameters • File location—
(if not
wired) Specifies the location of the file you want to open.

Specifies the operation to perform.

Contains the following options:

• open—Opens an existing file.

• open or create—Opens an existing file or creates a new file if one does not exist.
• create or replace—Creates a new file or replaces a file if it exists and you give
permission. This Express VI replaces a file by opening the file and setting its end
Overwrite
of file to 0.
options (if
• create—Creates a new file.
not wired)
• open (read only)—Opens an existing file for read only.

Note Only TDM and TDMS files support all the options listed above. If the
DataPlugin you specify in the DataPlugin list is not a .tdms or .tdm file,
LabVIEW uses the open (read only) option by default to open the data file.
To write to the data file, you can wire a create or create or replace control
to the function (open:0) block diagram input.

Install/ Launches the Install/Update DataPlugins dialog box which allows you to search,
Update install, and update DataPlugins from the National Instruments website at ni.com/
DataPlugins dataplugins.

1650 ni.com
 Functions

Inputs/Outputs
• file path —

Specifies the full path of the file you want to open.

• function (open:0) —

Specifies the operation to perform.

• DataPlugin name —

Specifies the name of the DataPlugin, which determines the storage format of the data file. To
open an external data file, you first must install the correct National Instruments DataPlugins.
Refer to the National Instruments website at ni.com/dataplugins to download DataPlugins. If
you do not wire data to this input, LabVIEW uses the value that you specify in the DataPlugin
dialog box option. If you wire data to this input, LabVIEW ignores the value of the DataPlugin
option. If you wire an empty string to this input, LabVIEW automatically detects the storage
format of the data file.

• additional parameters —

Specifies additional parameters for the input DataPlugin.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum (file) —

Generates a refnum to the file this Express VI opened.

• DataPlugin name out —

Returns DataPlugin name unchanged. If you do not wire data to the DataPlugin name input,
DataPlugin name out returns the value that you specify in the DataPlugin dialog box option. If
you wire an empty string to the DataPlugin name input, DataPlugin name out returns the
storage format that LabVIEW automatically detects.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1651

 Functions

Write Data

Adds a channel group or channel to a file you specify. You also can use this VI to define
properties for the channel group or channel that you want to add.

You also can use the Write To Measurement File Express VI to write data to a .tdm,
.tdms, or .lvm file.

Dialog Box Options

Option Description
Contains the following options:

• Object type—

Specifies the type of object to add to the file.

Contains the following options:

◦ Channel group—Adds a channel group to the file.
◦ Channel—Adds a channel to the file.
• Always create new channel group/channel—
Settings
Specifies whether to append existing channel groups or channels of the same
name. If you do not want to append existing channel groups or channels, place a
checkmark in this checkbox.

When a channel name is repeated, LabVIEW appends an integer to the end of the
names to enforce unique channel names. For example, if you provide the channel
names sine, sine, square, square, and sine, LabVIEW updates these names
to sine, sine 1, square, square 1, and sine 2, respectively.

Properties Contains the following options:

1652 ni.com
 Functions

Option Description

• TDM Properties—Use the TDM Properties tab to edit predefined properties and
create user-defined properties for .tdm and .tdms files. Click the Insert button
to add a new property to configure. Click the Delete button to remove the selected
property. For predefined properties, you can edit only the Source and Value
columns.
◦ Source—Use the Source column to specify the input source of the property
information. The Source column contains the following options:
▪ Terminal—Select this option if you want to specify the property
information on the block diagram.
▪ Ignore—Select this option if you do not want to write any of the property
information on the specified row to the file.
▪ Value—Select this option if you want to specify the property information
on the TDM Properties tab.
◦ Name—Use the Name column to specify the property name. The property
name cannot contain any spaces or special characters. LabVIEW automatically
replaces spaces and special characters with an underscore. This column
contains the following predefined property names:
▪ Name—Specifies the name of the object you select in Object type.
▪ Description—Specifies the description of the object you select in Object
type.
▪ Channel group—Specifies the channel group object for the data channel.
This property appears only if you select Channel in Object type.
▪ Unit—Specifies the unit of the channel values. This property appears only
if you select Channel in Object type.
▪ Waveform length—Specifies the number of samples in the waveform.
This property appears only if you select Channel in Object type
▪ Waveform x dimension—Specifies the name of the x dimension of the
waveform. This property appears only if you select Channel in Object
type.
▪ Waveform x unit—Specifies the unit of the x dimension of the waveform.
This property appears only if you select Channel in Object type.
▪ Waveform timestamp—Specifies the time stamp of the first sample in the
waveform. This property appears only if you select Channel in Object
type.
▪ Waveform offset—Specifies the starting point in the waveform. This
property appears only if you select Channel in Object type.
▪ Waveform increment—Specifies the time interval between every two
adjacent samples in the waveform. This property appears only if you
select Channel in Object type.

© National Instruments 1653

 Functions

Option Description

▪ Waveform time mode—Specifies the time mode of the waveform. You

can specify either an absolute or relative time mode. This property
appears only if you select Channel in Object type.
◦ Value—Use the Value column to specify the property value. The format of
Value is determined by your selection in the Data Type column. The value in
this column is not used if you selected the Terminal option in the Source
column.
◦ Data Type—Use the Data Type column to specify the data type of the Value
column. The Data Type column contains the following options:
▪ STR—Select this option to specify Value as a string.
▪ DBL—Select this option to specify Value as a double-precision, floating-
point number.
▪ TIME—Select this option to specify Value as a timestamp value.
▪ I32—Select this option to specify Value as a long integer number.
◦ Insert—Inserts a new input at the top of the list.
◦ Delete—Deletes the selected input from the list.
• DAQmx—Use the DAQmx Properties tab to select and edit DAQmx property names
for .tdm and .tdms files.

Options in this section are available only if you select Channel as the Object type.
Contains the following options:

• Show terminals for data channel—

Displays terminals for Signal, append/replace (append data values), and index on
Measured
the block diagram.
data
channel • Append/replace data values—Contains the following options:
◦ Append—Appends new values to the end of existing values.
◦ Replace at index—Replaces all existing values with new values.
◦ Replace all—Replaces values at the index you wire to index on the block
diagram.

Inputs/Outputs
• storage refnum (file) —

Specifies the reference number for the .tdm and .tdms file you want to access. You must wire a

1654 ni.com
 Functions

file refnum to this input.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• index —

Specifies where to replace values in the waveform. The default is 0.

• append / replace (append data values) —

Specifies whether you want to append new values to the end of existing values, replace all
existing values with new values, or replace values at the index you wire to the index input. This
input appears only if you place a checkmark in the Show terminals for data channel check box
in the configuration dialog box.

• Signal —

Specifies the signal to add to the an existing channel. This input appears only if you specify
Channel as the Object type in the configuration dialog box.

Note The Storage/DataPlugin VIs do not support strings that contain binary data.
You must first convert the string to an unsigned byte array using the String to Byte
Array function. If you do not convert the string, the Write Data Express VI writes only
the portion of the string before the first NULL character.

• storage refnum (file) out —

Returns a reference number for the .tdm and .tdms file this Express VI accesses. You can wire
this refnum to another VI to complete another operation on the same file.

• error out —

error out contains error information. This output provides standard error out functionality.

• storage refnum (channel) —

Returns an array of refnums that represent the channel groups or channels in the file. If you
select a property from the configuration dialog box and wire a value to compare to the
Comparison input, this refnum returns the channel groups or channels that meet the query
condition. If you do not specify a value to compare, this refnum returns all channel groups or

© National Instruments 1655

 Functions

channels.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\TDM\TDM Event Data\

TDM Event Data.lvproj

Read Data

Returns an array of refnums that represent channel groups or channels in the file. If
you select Channel as the Object type to read in the configuration dialog box, this VI
reads waveforms associated with the channel. You also can use this VI to return
channel groups or channels that meet query conditions you specify.

Use the Set Properties Express VI to define properties and the Get Properties Express VI
to return properties for the channel groups or channels this Express VI returns.

You also can use the Read From Measurement File Express VI to read data from a .tdm,
.tdms, or .lvm file.

Dialog Box Options

Option Description
Contains the following options:
Read
Settings • Object type to read—

1656 ni.com
 Functions

Option Description

Specifies the type of object to return.

Contains the following options:

◦ Channel group—Returns channel groups in the file.
◦ Channel—Returns channels in the channel group or file.

Contains the following options:

• Property to compare—

Specifies the property to compare when performing the query. If you select a
property from this list, a corresponding input and the Comparison input appear on
the block diagram. This Express VI compares the value you wire to the property to
the channels or channel groups the storage refnum identifies and returns channels
or channel groups that meet the comparison condition.

◦ query all data—Returns all data.

◦ Name—Name of the channel group or channel.
◦ Description—Description of the channel group or channel.
Query ◦ Unit—Name of a unit. This property is available only when you select Channel
as the Data type.
◦ Data type—Data type of the channel. This property is available only when you
select Channel as the Object type to read.
◦ Minimum—Minimum value of the channel. This property is available only
when you select Channel as the Object type to read.
◦ Maximum—Maximum value of the channel. This property is available only
when you select Channel as the Object type to read.
• Include only channels from the wired channel group—

Specifies whether to query all channels in the file or only channels in the channel
group. In order to place a checkmark in this checkbox, the incoming refnum must
be a channel group.

Contains the following options:

Measured • Show terminals—

data
Displays a terminal for Signal on the block diagram.
channels
• Output data channel as—Specifies the data type of the output. This option is

© National Instruments 1657

 Functions

Option Description

available only if you select Channel as the Object type to read and you place a
checkmark in the Show terminals checkbox. Contains the following options:
◦ Dynamic data type—Returns the output signals formatted as dynamic data.
◦ Array of waveforms—Returns the output signals formatted as a 1D array of
waveforms.
◦ Array of strings—Returns the output signals formatted as a 2D array of strings.
◦ Array of doubles—Returns the output signals formatted as a 2D array of
double-precision, floating-point numbers.
◦ Array of singles—Returns the output signals formatted as a 2D array of single-
precision, floating-point numbers.
◦ Array of I32—Returns the output signals formatted as a 2D array of 32-bit
signed integers.
◦ Array of I16—Returns the output signals formatted as a 2D array of 16-bit
signed integers.
◦ Array of U8—Returns the output signals formatted as a 2D array of 8-bit
unsigned integers.
◦ Array of time stamps—Returns the output signals formatted as a 2D array of
time stamp values.

Inputs/Outputs
• storage refnum (file) —

Specifies the reference number for the data object you want to access. After you wire a file
refnum to this input, the label changes from storage refnum to storage refnum (file). After you
wire a channel group refnum to this input, the label changes from storage refnum to storage
refnum (channel group). After you wire a channel refnum to this input, the label changes from
storage refnum to storage refnum (channel).

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• index —

Specifies where this Express VI starts reading values from a channel. This input appears only if
you select Channel as the Object type and if you place a checkmark in the Show terminals for
data channel check box in the configuration dialog box.

1658 ni.com
 Functions

• count —

Specifies the number of values for this Express VI to read from a channel. This input appears only
if you select Channel as the Object type and if you place a checkmark in the Show terminals for
data channel check box in the configuration dialog box.

• storage refnum (file) out —

Returns a reference number for the data object this Express VI accesses. You can wire this refnum
to another VI to complete another operation on the same object.

• error out —

error out contains error information. This output provides standard error out functionality.

• storage refnums (channel) —

Returns an array of refnums that represent the channel groups or channels in the file. If you
select a property from the configuration dialog box and wire a value to compare to the
Comparison input, this refnum returns the channel groups or channels that meet the query
condition. If you do not specify a value to compare, this refnum returns all channel groups or
channels.

• Signal —

Returns a signal formatted according to the data type you specified in the configuration dialog
box. This output appears only if you select Channel as the Object type and if you place a
checkmark in the Show terminals for data channel check box in the configuration dialog box.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\TDM\TDM Event Data\

TDM Event Data.lvproj

Close Data Storage

Closes a data file. You must use this Express VI to close a data file after you finish
reading from or writing to the file. Memory leakage might occur if you do not close the
data file.

© National Instruments 1659

 Functions

Dialog Box Options

Inputs/Outputs
• storage refnum —
Specifies the reference number for the data object you want to access. After you wire a file
refnum to this input, the label changes from storage refnum to storage refnum (file). After you
wire a channel group refnum to this input, the label changes from storage refnum to storage
refnum (channel group). After you wire a channel refnum to this input, the label changes from
storage refnum to storage refnum (channel).
• error in (no error) —
Describes error conditions that occur before this node runs.
• file path —
Returns the path that corresponds to storage refnum.
• error out —
Contains error information. This output provides standard error out functionality.

Set Properties

Defines the properties of an existing file, channel group, or channel. If you configure
this VI before you wire a refnum to storage refnum, the configuration might change
depending on the refnum you wire. For example, if you configure this VI for a channel
and then wire a channel group refnum, the VI returns broken wires on the block
diagram because the same properties are not available for a channel group.

1660 ni.com
 Functions

Dialog Box Options

Option Description
Contains the following options:

• Object type—

Specifies the type of object to add to the file.

Settings
◦ File—Sets properties for a file.
◦ Channel group—Sets properties for a channel group.
◦ Channel—Sets properties for a channel.

Contains the following options:

• TDM Properties—Use the TDM Properties tab to edit predefined properties and
create user-defined properties for .tdm and .tdms files. Click the Insert button
to add a new property to configure. Click the Delete button to remove the selected
property. For predefined properties, you can edit only the Source and Value
columns.
◦ Source—Use the Source column to specify the input source of the property
information. The Source column contains the following options:
▪ Terminal—Select this option if you want to specify the property
information on the block diagram.
▪ Ignore—Select this option if you do not want to write any of the property
information on the specified row to the file.
▪ Value—Select this option if you want to specify the property information
Properties on the TDM Properties tab.
◦ Name—Use the Name column to specify the property name. The property
name cannot contain any spaces or special characters. LabVIEW automatically
replaces spaces and special characters with an underscore. This column
contains the following predefined property names:
▪ Name—Specifies the name of the object you select in Object type.
▪ Description—Specifies the description of the object you select in Object
type.
▪ Title—Specifies the title of the data set in the .tdm or .tdms file. This
property appears only if you select File in Object type.
▪ Author—Specifies the author of the data set in the .tdm or .tdms file.
This property appears only if you select File in Object type.
▪ Time stamp—Specifies the time and date information when you last
saved the data set in the .tdm or .tdms file. This property appears only

© National Instruments 1661

 Functions

Option Description

if you select File in Object type.

▪ Unit—Specifies the unit of the channel values. This property appears only
if you select Channel in Object type.
▪ Waveform length—Specifies the number of samples in the waveform.
This property appears only if you select Channel in Object type
▪ Waveform x dimension—Specifies the name of the x dimension of the
waveform. This property appears only if you select Channel in Object
type.
▪ Waveform x unit—Specifies the unit of the x dimension of the waveform.
This property appears only if you select Channel in Object type.
▪ Waveform timestamp—Specifies the time stamp of the first sample in the
waveform. This property appears only if you select Channel in Object
type.
▪ Waveform offset—Specifies the starting point in the waveform. This
property appears only if you select Channel in Object type.
▪ Waveform increment—Specifies the time interval between every two
adjacent samples in the waveform. This property appears only if you
select Channel in Object type.
▪ Waveform time mode—Specifies the time mode of the waveform. You
can specify either an absolute or relative time mode. This property
appears only if you select Channel in Object type.
◦ Value—Use the Value column to specify the property value. The format of
Value is determined by your selection in the Data Type column. The value in
this column is not used if you selected the Terminal option in the Source
column.
◦ Data Type—Use the Data Type column to specify the data type of the Value
column. The Data Type column contains the following options:
▪ STR—Select this option to specify Value as a string.
▪ DBL—Select this option to specify Value as a double-precision, floating-
point number.
▪ TIME—Select this option to specify Value as a timestamp value.
▪ I32—Select this option to specify Value as a long integer number.
◦ Insert—Inserts a new input at the top of the list.
◦ Delete—Deletes the selected input from the list.
• DAQmx—Use the DAQmx Properties tab to select and edit DAQmx property names
for .tdm and .tdms files.

Measured
Options in this section are available only if you select Channel as the Object type.
data
Contains the following options:
channel

1662 ni.com
 Functions

Option Description

• Show terminals for data channel—

Displays terminals for Signal, append/replace (append data values), and index on
the block diagram.

• Append/replace data values—Contains the following options:

◦ Append—Appends new values to the end of existing values.
◦ Replace at index—Replaces all existing values with new values.
◦ Replace all—Replaces values at the index you wire to index on the block
diagram.

Inputs/Outputs
• storage refnum (channel) —

Specifies the reference number for the data object you want to access. After you wire a file
refnum to this input, the label changes from storage refnum to storage refnum (file). After you
wire a channel group refnum to this input, the label changes from storage refnum to storage
refnum (channel group). After you wire a channel refnum to this input, the label changes from
storage refnum to storage refnum (channel).

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• index —

Specifies where to replace values in the waveform. The default is 0.

• append / replace (append data values) —

Specifies whether you want to append new values to the end of existing values, replace all
existing values with new values, or replace values at the index you wire to the index input. This
input appears only if you place a checkmark in the Show terminals for data channel check box
in the configuration dialog box.

• Name —

Specifies the name of the object you select in Object type.

© National Instruments 1663

 Functions

• Description —

Specifies the description of the object you select in Object type.

• Unit —

Specifies the unit of the channel values. This property appears only if you select Channel in
Object type.

• Signal —

Specifies the signal to add to the an existing channel. This input appears only if you specify
Channel as the Object type in the configuration dialog box.

Note The Storage/DataPlugin VIs do not support strings that contain binary data.
You must first convert the string to an unsigned byte array using the String to Byte
Array function. If you do not convert the string, the Write Data Express VI writes only
the portion of the string before the first NULL character.

• storage refnum (channel) out —

Returns a reference number for the data object this Express VI accesses. You can wire this refnum
to another VI to complete another operation on the same object.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Properties

Reads property values from a file, channel group, or channel. If you configure this VI
before you wire a refnum to storage refnum, the configuration might change
depending on the refnum you wire. For example, if you configure this VI for a channel
and then wire a channel group refnum, the VI returns broken wires on the block
diagram because the same properties are not available for a channel group.

1664 ni.com
 Functions

Dialog Box Options

Option Description
Contains the following options:

• Object type—

Specifies the type of data for which you want to get properties.
Settings
◦ File—Reads properties from a file.
◦ Channel group—Reads properties from a channel group.
◦ Channel—Reads properties from a channel.

Contains the following options:

• TDM Properties—Use the TDM Properties tab to edit predefined properties and
create user-defined properties for .tdm and .tdms files. Click the Insert button
to add a new property to configure. Click the Delete button to remove the selected
property. For predefined properties, you can edit only the Source and Value
columns.
◦ Source—Use the Source column to specify the input source of the property
information. The Source column contains the following options:
▪ Terminal—Select this option if you want to specify the property
information on the block diagram.
Properties
▪ Ignore—Select this option if you do not want to write any of the property
information on the specified row to the file.
◦ Name—Use the Name column to specify the property name. The property
name cannot contain any spaces or special characters. LabVIEW automatically
replaces spaces and special characters with an underscore. This column
contains the following predefined property names:
▪ Name—Specifies the name of the object you select in Object type.
▪ Description—Specifies the description of the object you select in Object
type.
▪ Title—Specifies the title of the data set in the .tdm or .tdms file. This

© National Instruments 1665

 Functions

Option Description

property appears only if you select File in Object type.

▪ Author—Specifies the author of the data set in the .tdm or .tdms file.
This property appears only if you select File in Object type.
▪ Time stamp—Specifies the time and date information when you last
saved the data set in the .tdm or .tdms file. This property appears only
if you select File in Object type.
▪ Channel groups—Specifies the channel group objects for the data set in
the .tdm or .tdms file. This property appears only if you select File in
Object type.
▪ File—Specifies the file object for the channel group. This property
appears only if you select Channel group in Object type.
▪ Channels—Specifies the channel objects for the channel group. This
property appears only if you select Channel group in Object type.
▪ Channel group—Specifies the channel group object for the data channel.
This property appears only if you select Channel in Object type.
▪ Unit—Specifies the unit of the channel values. This property appears only
if you select Channel in Object type.
▪ Data type—Specifies the data type of the channel values. This property
appears only if you select Channel in Object type.
▪ Minimum—Specifies the lowest channel value. This property appears
only if you select Channel in Object type.
▪ Maximum—Specifies the highest channel value. This property appears
only if you select Channel in Object type.
▪ Waveform length—Specifies the number of samples in the waveform.
This property appears only if you select Channel in Object type
▪ Waveform x dimension—Specifies the name of the x dimension of the
waveform. This property appears only if you select Channel in Object
type.
▪ Waveform x unit—Specifies the unit of the x dimension of the waveform.
This property appears only if you select Channel in Object type.
▪ Waveform timestamp—Specifies the time stamp of the first sample in the
waveform. This property appears only if you select Channel in Object
type.
▪ Waveform offset—Specifies the starting point in the waveform. This
property appears only if you select Channel in Object type.
▪ Waveform increment—Specifies the time interval between every two
adjacent samples in the waveform. This property appears only if you
select Channel in Object type.
▪ Waveform time mode—Specifies the time mode of the waveform. You

1666 ni.com
 Functions

Option Description

can specify either an absolute or relative time mode. This property

appears only if you select Channel in Object type.
◦ Value—Use the Value column to specify the property value. The format of
Value is determined by your selection in the Data Type column. The value in
this column is not used if you selected the Terminal option in the Source
column.
◦ Data Type—Use the Data Type column to specify the data type of the Value
column. The Data Type column contains the following options:
▪ STR—Select this option to specify Value as a string.
▪ DBL—Select this option to specify Value as a double-precision, floating-
point number.
▪ TIME—Select this option to specify Value as a timestamp value.
▪ I32—Select this option to specify Value as a long integer number.
◦ Insert—Inserts a new input at the top of the list.
◦ Delete—Deletes the selected input from the list.
• DAQmx—Use the DAQmx Properties tab to select and edit DAQmx property names
for .tdm and .tdms files.

Contains the following options:

• Show terminals for data channel—

Displays terminals for Signal, index, and count on the block diagram.

• Output data channel as—

Specifies the data type of the output. This option is available only if you select
Channel as the Object type and if you place a checkmark in the Show terminals
Measured for data channel check box.
data
channel ◦ Dynamic data type—Returns the output signal formatted as dynamic data.
◦ Waveform—Returns the output signal formatted as a waveform.
◦ Array of strings—Returns the output signal formatted as a 1D array of strings.
◦ Array of doubles—Returns the output signal formatted as a 1D array of
double-precision, floating-point numbers.
◦ Array of singles—Returns the output signal formatted as a 1D array of single-
precision, floating-point numbers.
◦ Array of I32—Returns the output signal formatted as a 1D array of 32-bit
signed integers.
◦ Array of I16—Returns the output signal formatted as a 1D array of 16-bit

© National Instruments 1667

 Functions

Option Description

signed integers.
◦ Array of U8—Returns the output signal formatted as a 1D array of 8-bit
unsigned integers.
◦ Array of time stamps—Returns the output signal as a 1D array of time stamp
values.

Inputs/Outputs
• storage refnum (channel) —

Specifies the reference number for the data object you want to access. After you wire a file
refnum to this input, the label changes from storage refnum to storage refnum (file). After you
wire a channel group refnum to this input, the label changes from storage refnum to storage
refnum (channel group). After you wire a channel refnum to this input, the label changes from
storage refnum to storage refnum (channel).

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• index —

Specifies where this Express VI starts reading values from a channel. This input appears only if
you select Channel as the Object type and if you place a checkmark in the Show terminals for
data channel check box in the configuration dialog box.

• count —

Specifies the number of values for this Express VI to read from a channel. This input appears only
if you select Channel as the Object type and if you place a checkmark in the Show terminals for
data channel check box in the configuration dialog box.

• storage refnum (channel) out —

Returns a reference number for the data object this Express VI accesses. You can wire this refnum
to another VI to complete another operation on the same object.

• error out —

1668 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

• Name —

Specifies the name of the object you select in Object type.

• Unit —

Specifies the unit of the channel values. This property appears only if you select Channel in
Object type.

• Signal —

Returns a signal formatted according to the data type you specified in the configuration dialog
box. This output appears only if you select Channel as the Object type and if you place a
checkmark in the Show terminals for data channel check box in the configuration dialog box.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\TDM\TDM Channel

Groups\TDM Channel Groups.lvproj

Delete Data

Removes a channel group or channel you specify. If you choose to delete a channel
group, this VI deletes all channels associated with that channel group. Wire data to the
storage refnum input to determine the polymorphic instance to use or manually select
the instance.

Note This VI does not delete data in .tdms files.

• Delete Channel VI

© National Instruments 1669

 Functions

• Delete Channel Group VI

Delete Channel VI
Removes a channel group or channel you specify. If you choose to delete a channel
group, this VI deletes all channels associated with that channel group. Wire data to the
storage refnum input to determine the polymorphic instance to use or manually select
the instance.

Note This VI does not delete data in .tdms files.

Inputs/Outputs
• storage refnum (channel) —

storage refnum (channel) specifies the channel to remove.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Delete Channel Group VI

Removes a channel group or channel you specify. If you choose to delete a channel
group, this VI deletes all channels associated with that channel group. Wire data to the
storage refnum input to determine the polymorphic instance to use or manually select
the instance.

1670 ni.com
 Functions

Note This VI does not delete data in .tdms files.

Inputs/Outputs
• storage refnum (channel group) —

storage refnum (channel group) specifies the channel group to remove.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Data File Viewer

Opens the data file specified in the file path input and presents the data in the Data
File Viewer dialog box.

Inputs/Outputs
• file path —

file path is the absolute path to the file you want to open.

• DataPlugin name —

DataPlugin name specifies the name of the DataPlugin that determines the storage format of

© National Instruments 1671

 Functions

the data file. Use the List DataPlugins VI to obtain the names of all DataPlugins installed on the
local computer. If you do not wire data to this input or if you wire an empty string to this input,
this VI automatically detects the storage format of the data file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• file path out —

file path out returns file path unchanged.

• DataPlugin name out —

DataPlugin name out returns DataPlugin name unchanged. If you do not wire the DataPlugin
name input or if you wire an empty string to this input, DataPlugin name out returns the
DataPlugin name that this VI detects automatically.

• error out —

error out contains error information. This output provides standard error out functionality.

Convert to TDM or TDMS

Converts the specified file to the .tdm or .tdms file format.

Inputs/Outputs
• DataPlugin name —

DataPlugin name specifies the name of the DataPlugin that determines the storage format of
the data file. Use the List DataPlugins VI to obtain the names of all DataPlugins installed on the

1672 ni.com
 Functions

local computer. If you do not wire data to this input or if you wire an empty string to this input,
this VI automatically detects the storage format of the data file.

• source file path —

source file path specifies the path to the data file you want to convert.

• target file path —

target file path specifies the path to the new .tdm or .tdms file you want to create.

• target file operation (3:create) —

target file operation specifies the operation to perform.

open
0
—Opens a file to configure.
open or create
1
—Opens an existing file or creates a new file to configure.
create or replace
2
—Creates a new file or replaces an existing file.
create
3
(Default)—Creates a new file.
open (read only)
4
—Opens a read-only version of the file.

• target file format (TDMS) —

target file format specifies the target file format to which you want to convert the data file.

TDM
0
—Converts the data file to a .tdm file.
TDMS
1
(Default)—Converts the data file to a .tdms file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data chunk size (1E+7) —

© National Instruments 1673

 Functions

data chunk size specifies the number of values to read into memory at a time until this VI
finishes reading all values. If you have enough system memory, use a higher number than the
default value to achieve better performance. The default is 1E+7.

• DataPlugin name out —

DataPlugin name out returns DataPlugin name unchanged. If you do not wire the DataPlugin
name input or if you wire an empty string to this input, DataPlugin name out returns the
DataPlugin name that this VI detects automatically.

• source file path out —

source file path out returns source file path unchanged.

• target file path out —

target file path out returns target file path unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Manage DataPlugins

Use the Manage DataPlugins VIs to list, export, register, or unregister DataPlugins
installed on the local computer.

Note DataPlugins are shared between different National Instruments

products and applications on the local computer. Registering or unregistering
a DataPlugin might affect these products or applications.

The VIs on this palette can return storage error codes.

1674 ni.com
 Functions

Palette
Description
Object

Lists all DataPlugins existing on the National Instruments website at ni.com/

List
dataplugins or registered on the local computer. You also can use this VI to search for
DataPlugins
a DataPlugin that exists on the local computer or the National Instruments website.

Export
Exports a DataPlugin that exists on the local computer to a .uri file.
DataPlugin

Register Registers or installs a DataPlugin to the local computer. You must manually select the
DataPlugin polymorphic instance to use.

Unregister Unregisters a DataPlugin from the local computer. This VI does not delete the
DataPlugin corresponding DataPlugin .uri file or installer from the computer.

List DataPlugins
Lists all DataPlugins existing on the National Instruments website at ni.com/
dataplugins or registered on the local computer. You also can use this VI to search for a
DataPlugin that exists on the local computer or the National Instruments website.

Note Use the Register DataPlugin VI to register or install DataPlugins on the

local computer.

Inputs/Outputs
• DataPlugin name —

© National Instruments 1675

 Functions

DataPlugin name specifies the name of the DataPlugin you want to search for. If you do not wire
data to this input or if you wire an empty string to this input, this VI lists all DataPlugins
registered on the local computer or exist on the National Instruments website.

• file extension —

file extension specifies the file extension of a DataPlugin.

• source —

source specifies the source location where you want to search for the DataPlugins.

0 local machine (default)—Lists or searches DataPlugins installed on the local computer.

web—Lists or searches DataPlugins from the National Instruments website at ni.com/
1
dataplugins.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• DataPlugin information —

DataPlugin information returns information about each DataPlugin.

• name —

name returns the name of the DataPlugin.

• version —

version returns the version information of the DataPlugin.

• type —

type returns the type of the DataPlugin. This information indicates the programming
language in which the DataPlugin was created.

• read-only? —

read-only? indicates whether the DataPlugin is a read-only DataPlugin.

1676 ni.com
 Functions

• extensions —

extensions returns the file extensions you can use with this DataPlugin.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\General\Manage
DataPlugins.vi

Export DataPlugin
Exports a DataPlugin that exists on the local computer to a .uri file.

Note You can export only DataPlugins with a type of VBS or VBCrypt. Use the
List DataPlugins VI to view the type of a DataPlugin.

Inputs/Outputs
• DataPlugin URI path (*.uri) —

DataPlugin URI path (*.uri) specifies the path to which you want to export the DataPlugin.

• DataPlugin name —

© National Instruments 1677

 Functions

DataPlugin name specifies the name of the DataPlugin you want to export.

• encrypt? (F) —

encrypt? specifies whether to encrypt the .uri file when you export the DataPlugin. The
default is FALSE. This VI ignores this input if you export a DataPlugin with a type of VBCrypt.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• DataPlugin URI path out —

DataPlugin URI path out returns DataPlugin URI path (*.uri) unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\General\Manage
DataPlugins.vi

Register DataPlugin
Registers or installs a DataPlugin to the local computer. You must manually select the
polymorphic instance to use.

Note DataPlugins are shared between different National Instruments

products and applications on the local computer. Installing/registering or
uninstalling/unregistering a DataPlugin might affect these products or
applications.

1678 ni.com
 Functions

• Register DataPlugin by URI VI

• Install DataPlugin by Name VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\General\Manage
DataPlugins.vi
• labview\examples\File IO\DataPlugins\ATML\DataPlugins -
ATML.lvproj

Register DataPlugin by URI VI

Registers or installs a DataPlugin to the local computer. You must manually select the
polymorphic instance to use.

Note DataPlugins are shared between different National Instruments

products and applications on the local computer. Installing/registering or
uninstalling/unregistering a DataPlugin might affect these products or
applications.

Inputs/Outputs
• DataPlugin URI path (*.uri) —

DataPlugin URI path (*.uri) specifies the path to the DataPlugin .uri file. You can download
DataPlugin .uri files from the National Instruments website at ni.com/dataplugins.

• error in (no error) —

© National Instruments 1679

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• DataPlugin URI path out —

DataPlugin URI path out returns DataPlugin URI path (*.uri) unchanged.

• DataPlugin information —

DataPlugin information returns information about the DataPlugin that this VI registers on the
local computer.

• name —

name returns the name of the DataPlugin.

• version —

version returns the version information of the DataPlugin.

• type —

type returns the type of the DataPlugin. This information indicates the programming
language in which the DataPlugin was created.

• read-only? —

read-only? indicates whether the DataPlugin is a read-only DataPlugin.

• extensions —

extensions returns the file extensions you can use with this DataPlugin.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

1680 ni.com
 Functions

• labview\examples\File IO\DataPlugins\General\Manage
DataPlugins.vi
• labview\examples\File IO\DataPlugins\ATML\DataPlugins -
ATML.lvproj

Install DataPlugin by Name VI

Registers or installs a DataPlugin to the local computer. You must manually select the
polymorphic instance to use.

Note DataPlugins are shared between different National Instruments

products and applications on the local computer. Installing/registering or
uninstalling/unregistering a DataPlugin might affect these products or
applications.

Inputs/Outputs
• DataPlugin name —

DataPlugin name specifies the name of the DataPlugin. You can find the DataPlugin names on
the National Instruments website at ni.com/dataplugins or use the List DataPlugins VI to list all
the DataPlugins existing on the website.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• DataPlugin name out —

DataPlugin name out returns a duplicate of DataPlugin name.

• DataPlugin information —

© National Instruments 1681

 Functions

DataPlugin information returns information about the DataPlugin that this VI installs on the
local computer.

• name —

name returns the name of the DataPlugin.

• version —

version returns the version information of the DataPlugin.

• Type —

type returns the type of the DataPlugin. This information indicates the programming
language in which the DataPlugin was created.

• read-only? —

read-only? indicates whether the DataPlugin is a read-only DataPlugin.

• extensions —

extensions returns the file extensions you can use with this DataPlugin.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\General\Manage
DataPlugins.vi
• labview\examples\File IO\DataPlugins\ATML\DataPlugins -
ATML.lvproj

1682 ni.com
 Functions

Unregister DataPlugin
Unregisters a DataPlugin from the local computer. This VI does not delete the
corresponding DataPlugin .uri file or installer from the computer.

Note DataPlugins are shared between different National Instruments

products and applications on the local computer. Registering or unregistering
a DataPlugin might affect these products or applications.

Inputs/Outputs
• DataPlugin name —

DataPlugin name specifies the name of the DataPlugin you want to unregister.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\DataPlugins\General\Manage
DataPlugins.vi

© National Instruments 1683

 Functions

Advanced Storage

Use the Advanced Storage VIs to read, write, and query data when object types or
property names are determined at run time.

The VIs on this palette can return storage error codes.

Palette
Description
Object

Get Object
Returns information about the object you specify.
Info

Get
Property Retrieves the properties of a data file, channel group, or channel.
Info

Set Defines a property for a file, channel group, or channel. Wire data to the Value input to
Property determine the polymorphic instance to use or manually select the instance.

Get Returns the value of a property for a file, channel group, or channel. You must
Property manually select the polymorphic instance you want to use.

Merges two arrays of storage reference numbers into one larger array of refnums. This
Merge
VI works properly only if the two sets of storage refnums are from the same data file.
Storage
Wire data to either of the storage refnums inputs to determine the polymorphic
Refnums
instance to use or manually select the instance.

Create Creates a query expression to use with the Execute Query Expression VI to search for
Query objects that meet the condition you specify. Wire data to the value input to determine
Expression the polymorphic instance to use or manually select the instance.

1684 ni.com
 Functions

Palette
Description
Object

Merge
Merges two query expressions. You can use the Create Query Expression VI to create
Query
query expressions that you want to merge.
Expressions

Execute
Query Returns data objects that meet the query expression.
Expression

Refnum to
Returns the ID for a data object.
ID

ID to Returns a refnum for an object you specify. Wire data to the storage refnum input to
Refnum determine the polymorphic instance to use.

Get Object Info

Returns information about the object you specify.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage read-only —

© National Instruments 1685

 Functions

storage read-only specifies if the data storage is read only.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• object type —

object type returns the data object type (file, channel group, or channel).

• storage location —

storage location returns the file path to the data storage.

• error out —

error out contains error information. This output provides standard error out functionality.

• DataPlugin name —

DataPlugin name returns the DataPlugin name that the data object contains.

Get Property Info

Retrieves the properties of a data file, channel group, or channel.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

1686 ni.com
 Functions

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• properties —

properties returns the properties of the data file, channel group, or channel.

• object type —

object type returns the type of the storage object that you wire to storage refnum.

• property name —

property name returns the name of the property. Use the Set Property VI to create property
names.

• data type —

data type returns the data type of the storage object.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property
Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

• Set Property (String) VI

• Set Property (DBL) VI
• Set Property (SGL) VI
• Set Property (I32) VI
• Set Property (I16) VI
• Set Property (U8) VI

© National Instruments 1687

 Functions

• Set Property (Enum) VI

• Set Property (Time Stamp) VI
• Set Property (Storage Refnum) VI
• Set Property (Storage Refnums) VI

Set Property (String) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the
property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

1688 ni.com
 Functions

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (DBL) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the
property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

© National Instruments 1689

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (SGL) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the
property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

1690 ni.com
 Functions

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (I32) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the
property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

© National Instruments 1691

 Functions

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (I16) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the
property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

1692 ni.com
 Functions

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (U8) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the

© National Instruments 1693

 Functions

property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (Enum) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

1694 ni.com
 Functions

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the numeric value of the enum.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Enum values —

enum values specifies the valid string values for the enum.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (Time Stamp) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

© National Instruments 1695

 Functions

Inputs/Outputs
• Create if not found (no:F) —

Create if not found specifies whether the VI creates a new property with the values you set if the
property specified in Property name does not exist. The default is FALSE, which means the VI
does not create a property and returns an error if the specified property does not exist.

• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (Storage Refnum) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to

1696 ni.com
 Functions

determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Property (Storage Refnums) VI

Defines a property for a file, channel group, or channel. Wire data to the Value input to
determine the polymorphic instance to use or manually select the instance.

© National Instruments 1697

 Functions

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• Value —

Value specifies the value of the property.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Property
Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

1698 ni.com
 Functions

• Get Property (String) VI

• Get Property (DBL) VI
• Get Property (SGL) VI
• Get Property (I32) VI
• Get Property (I16) VI
• Get Property (U8) VI
• Get Property (Enum) VI
• Get Property (Time Stamp) VI
• Get Property (Storage Refnum) VI
• Get Property (Storage Refnums) VI

Get Property (String) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

© National Instruments 1699

 Functions

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Property (DBL) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

1700 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Get Property (SGL) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1701

 Functions

Get Property (I32) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

1702 ni.com
 Functions

Get Property (I16) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1703

 Functions

Get Property (U8) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the Value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

1704 ni.com
 Functions

Get Property (Enum) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• String —

string returns the string value of the enum.

• Value —

Value returns the numeric value of the enum.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1705

 Functions

Get Property (Time Stamp) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

1706 ni.com
 Functions

Get Property (Storage Refnum) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1707

 Functions

Get Property (Storage Refnums) VI

Returns the value of a property for a file, channel group, or channel. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Property name —

Property name specifies the name of the property. Use the Get Property Info VI to obtain the
Property name.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• Value —

Value returns the value of the property.

• error out —

error out contains error information. This output provides standard error out functionality.

1708 ni.com
 Functions

Merge Storage Refnums

Merges two arrays of storage reference numbers into one larger array of refnums. This
VI works properly only if the two sets of storage refnums are from the same data file.
Wire data to either of the storage refnums inputs to determine the polymorphic
instance to use or manually select the instance.

• Merge Storage Refnums (Channel) VI

• Merge Storage Refnums (Channel group) VI

Merge Storage Refnums (Channel) VI

Merges two arrays of storage reference numbers into one larger array of refnums. This
VI works properly only if the two sets of storage refnums are from the same data file.
Wire data to either of the storage refnums inputs to determine the polymorphic
instance to use or manually select the instance.

Inputs/Outputs
• storage refnums (channel) 1 —

storage refnums (channel) 1 specifies the channels to merge. Wire the storage refnums output
of the Read Data VI to this input.

• storage refnums (channel) 2 —

storage refnums (channel) 2 specifies the channels to merge. Wire the storage refnums output
of the Read Data VI to this input.

• operation —

© National Instruments 1709

 Functions

operation specifies the condition that joins storage refnums (channel) 1 and storage refnums
(channel) 2.

AND
0 —Combines all channels that are included in both storage refnums (channel) 1 and storage
refnums (channel) 2.
OR
1
—Combines all channels from storage refnums (channel) 1 and storage refnums (channel) 2.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnums (channel) —

storage refnums (channel) returns the channels that meet the operation condition.

• error out —

error out contains error information. This output provides standard error out functionality.

Merge Storage Refnums (Channel group) VI

Merges two arrays of storage reference numbers into one larger array of refnums. This
VI works properly only if the two sets of storage refnums are from the same data file.
Wire data to either of the storage refnums inputs to determine the polymorphic
instance to use or manually select the instance.

Inputs/Outputs
• storage refnums (channel group) 2 —

1710 ni.com
 Functions

storage refnums (channel group) 2 specifies the channel groups to merge. Wire the storage
refnums output of the Read Data VI to this input.

• storage refnums (channel group) 1 —

storage refnums (channel group) 1 specifies the channel groups to merge. Wire the storage
refnums output of the Read Data VI to this input.

• operation —

operation specifies the condition that joins storage refnums (channel group) 1 and storage
refnums (channel group) 2.

AND—Combines all channel groups that are included in both storage refnums (channel group)
0
1 and storage refnums (channel group) 2.
OR—Combines all channel groups from storage refnums (channel group) 1 and storage
1
refnums (channel group) 2.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnums (channel group) —

storage refnums (channel group) returns the channel groups that meet the operation
condition.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Query Expression

Creates a query expression to use with the Execute Query Expression VI to search for
objects that meet the condition you specify. Wire data to the value input to determine
the polymorphic instance to use or manually select the instance.

© National Instruments 1711

 Functions

• Create Query Expression (String) VI

• Create Query Expression (I32) VI
• Create Query Expression (DBL) VI
• Create Query Expression (Time Stamp) VI

Create Query Expression (String) VI

Creates a query expression to use with the Execute Query Expression VI to search for
objects that meet the condition you specify. Wire data to the value input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• property name —

property name specifies the name of the property. Use the Get Property Info VI to obtain the
property name.

• comparison operator (=) —

comparison operator (=) specifies the comparison condition.

0 =
1 !=
2 >
3 <
4 >=
5 <=

• value —

1712 ni.com
 Functions

value specifies the value you want to compare.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• query expression —

query expression returns a query expression based on what you wired to the inputs.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Query Expression (I32) VI

Creates a query expression to use with the Execute Query Expression VI to search for
objects that meet the condition you specify. Wire data to the value input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• property name —

property name specifies the name of the property. Use the Get Property Info VI to obtain the
property name.

• comparison operator (=) —

comparison operator (=) specifies the comparison condition.

0 =

© National Instruments 1713

 Functions

1 !=
2 >
3 <
4 >=
5 <=

• value —

value specifies the value you want to compare.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• query expression —

query expression returns a query expression based on what you wired to the inputs.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Query Expression (DBL) VI

Creates a query expression to use with the Execute Query Expression VI to search for
objects that meet the condition you specify. Wire data to the value input to determine
the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• property name —

property name specifies the name of the property. Use the Get Property Info VI to obtain the

1714 ni.com
 Functions

property name.

• comparison operator (=) —

comparison operator (=) specifies the comparison condition.

0 =
1 !=
2 >
3 <
4 >=
5 <=

• value —

value specifies the value you want to compare.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• query expression —

query expression returns a query expression based on what you wired to the inputs.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Query Expression (Time Stamp) VI

Creates a query expression to use with the Execute Query Expression VI to search for
objects that meet the condition you specify. Wire data to the value input to determine
the polymorphic instance to use or manually select the instance.

© National Instruments 1715

 Functions

Inputs/Outputs
• property name —

property name specifies the name of the property. Use the Get Property Info VI to obtain the
property name.

• comparison operator (=) —

comparison operator (=) specifies the comparison condition.

0 =
1 !=
2 >
3 <
4 >=
5 <=

• value —

value specifies the value you want to compare.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• query expression —

query expression returns a query expression based on what you wired to the inputs.

• error out —

error out contains error information. This output provides standard error out functionality.

1716 ni.com
 Functions

Merge Query Expressions

Merges two query expressions. You can use the Create Query Expression VI to create
query expressions that you want to merge.

Inputs/Outputs
• query expression 1 —

query expression 1 specifies a query expression you want to merge.

• query expression 2 —

query expression 2 specifies a query expression you want to merge.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• combined query expression —

combined query expression returns a query expression that merges query expression 1 and
query expression 2. You can wire this output to the Execute Query Expression VI to obtain the
objects that meet the combined query conditions.

• error out —

error out contains error information. This output provides standard error out functionality.

Execute Query Expression

Returns data objects that meet the query expression.

© National Instruments 1717

 Functions

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• object type —

object type specifies the object type of the storage refnums that this VI returns. Use the Get
Object Info VI to obtain the object type from a storage refnum.

• query expression —

query expression specifies the query condition. Use the Create Query Expression VI to obtain the
query expression.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• storage refnums —

storage refnums returns the data objects that meet the query conditions.

• error out —

error out contains error information. This output provides standard error out functionality.

Refnum to ID
Returns the ID for a data object.

1718 ni.com
 Functions

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• storage refnum out —

storage refnum out returns a reference number for the data object this VI accesses.

• object ID —

object ID returns the object ID, which is a unique string that identifies the object in the file. The
object ID is persistent, so you can reuse it after closing a file and opening the file again.

• error out —

error out contains error information. This output provides standard error out functionality.

ID to Refnum
Returns a refnum for an object you specify. Wire data to the storage refnum input to
determine the polymorphic instance to use.

• GetObjectFromID_Storage VI
• GetObjectFromID_Object VI

© National Instruments 1719

 Functions

GetObjectFromID_Storage VI
Returns a refnum for an object you specify. Wire data to the storage refnum input to
determine the polymorphic instance to use.

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• object ID —

object ID specifies the ID of the object you want to access. The object ID is a unique string that
identifies the object in the file. Use the Refnum to ID VI to obtain the object ID.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• new storage refnum —

new storage refnum returns a refnum for the object.

• error out —

error out contains error information. This output provides standard error out functionality.

GetObjectFromID_Object VI
Returns a refnum for an object you specify. Wire data to the storage refnum input to
determine the polymorphic instance to use.

1720 ni.com
 Functions

Inputs/Outputs
• storage refnum —

storage refnum specifies the reference number for the data object you want to access.

• Object id —

object ID specifies the ID of the object you want to access. The object ID is a unique string that
identifies the object in the file. Use the Refnum to ID VI to obtain the object ID.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• new storage refnum —

new storage refnum returns a refnum for the object.

• error out —

error out contains error information. This output provides standard error out functionality.

Zip

Use the Zip VIs to create new zip files, to add files to zip files, to unzip zip files, and to
close zip files.

Palette
Description
Object
New
Zip Creates a new empty zip file in the path that target specifies. The new file overwrites an
File

© National Instruments 1721

 Functions

Palette
Description
Object

existing file or produces a confirmation dialog based on the value of the confirm
overwrite? control.

Add
Adds the file source file path specifies to a zip file. The destination path in zip control
File to
specifies the zipped path information.
Zip

Close
Zip Closes the zip file zip file in specifies.
File
Unzips the contents of Zip file to the Target directory. Set Preview only? to TRUE to
Unzip preview the list of files in Zip file before you unzip the zip file. This VI cannot unzip a zip file
that is password protected.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Zip\Create Zip File.vi

New Zip File

Creates a new empty zip file in the path that target specifies. The new file overwrites
an existing file or produces a confirmation dialog based on the value of the confirm
overwrite? control.

Inputs/Outputs
• target —

target specifies the path to the new or existing zip file. The VI deletes and rewrites the file if it

1722 ni.com
 Functions

already exists. You cannot append data to a zip file.

• confirm overwrite? (F) —

confirm overwrite? specifies to overwrite the existing zip file. The default is FALSE. If you set
confirm overwrite? to TRUE, the VI prompts you to confirm deleting the existing zip file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• zip file out —

zip file out returns the open zip file. zip file out is analogous to a refnum or task ID.

• cancelled —

cancelled returns TRUE only if a user cancels an overwrite confirmation dialog box.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Zip\Create Zip File.vi

Add File to Zip

Adds the file source file path specifies to a zip file. The destination path in zip control
specifies the zipped path information.

© National Instruments 1723

 Functions

Inputs/Outputs
• zip file in —

zip file in specifies the open zip file.

• source file path —

source file path specifies the path to file to add to the zip file.

• destination path in zip —

destination path in zip specifies the filename and the path to apply to the source file when the
VI encodes the file into the zip file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• zip file out —

zip file out returns the open zip file. zip file out is analogous to a refnum or task ID.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Zip\Create Zip File.vi

Close Zip File

Closes the zip file zip file in specifies.

1724 ni.com
 Functions

Inputs/Outputs
• zip file in —

zip file in specifies the open zip file.

• comments —

comments includes text to include in the zip file.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Zip\Create Zip File.vi

Unzip

Unzips the contents of Zip file to the Target directory. Set Preview only? to TRUE to
preview the list of files in Zip file before you unzip the zip file. This VI cannot unzip a zip
file that is password protected.

Inputs/Outputs
• Zip file —

© National Instruments 1725

 Functions

Zip file specifies the path to the zip file that you want to unzip.

• Preview only? —

Preview only? specifies whether to display the files in Zip file without unzipping the zip file. If
TRUE, this VI does not unzip Zip file and Preview displays a list of the files in the zip file. The
default is FALSE.

• Target directory (same as Zip file if empty) —

Target directory specifies the directory path to which the VI unzips the files in Zip file. The
default is the directory path that contains the zip file.

If you specify a path that includes a filename, the VI strips the filename from the path and unzips
files to the resulting directory.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Unzipped files —

Unzipped files lists the files that the VI unzips.

• Preview —

Preview lists the paths to the files in Zip file.

• error out —

error out contains error information. This output provides standard error out functionality.

XML

Use the XML VIs and functions to manipulate XML data.

1726 ni.com
 Functions

Palette Object Description

LabVIEW Use the LabVIEW Schema VIs and functions to manipulate LabVIEW data in XML
Schema format.

Use the XML Parser VIs and nodes to process XML documents using the XML parser.
XML Parser
The XML parser in LabVIEW is the Xerces 2.7 parser which uses a document object
model (DOM).

LabVIEW Schema

Use the LabVIEW Schema VIs and functions to manipulate LabVIEW data in XML format.

Palette
Description
Object
Flatten
Converts any data type you wire to anything and converts it to an XML string according
To XML
to the LabVIEW XML schema.
Function
Unflatten
From XML Converts an XML string to a LabVIEW data type according to the LabVIEW XML schema.
Function

Writes a text string of XML data with accompanying header tags to a text file. Wire data
Write to
to the XML Input input to determine the polymorphic instance to use or manually select
XML File
the instance. All XML data must follow the standard LabVIEW XML schema.

Reads and parses tags from a LabVIEW XML file. When you place this VI on the block
Read
diagram, the polymorphic VI selector is visible. Use this selector to choose which
From XML
polymorphic instance to use. All XML data must follow the standard LabVIEW XML
File
schema.

© National Instruments 1727

 Functions

Palette
Description
Object

Escape
Converts special characters to XML syntax according to the LabVIEW XML schema.
XML

Unescape Converts the XML syntax for special characters back to the special characters according
XML to the LabVIEW XML schema.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

Flatten To XML Function

Converts any data type you wire to anything and converts it to an XML string according
to the LabVIEW XML schema.

If anything contains the characters <, >, or &, the function converts those characters to
&lt;, &gt;, or &amp;, respectively. Use the Escape XML VI to convert other
characters, such as ", to XML syntax.

Inputs/Outputs
• anything —

anything is any LabVIEW data you want to convert. This parameter is polymorphic.

• xml string —

1728 ni.com
 Functions

xml string is the resulting XML string that represents the LabVIEW data type.

When converting decimal values, this function uses only the period (.) as a decimal separator.
The function does not use localized decimal separators.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

Unflatten From XML Function

Converts an XML string to a LabVIEW data type according to the LabVIEW XML schema.

If xml string contains the characters &lt;, &gt;, or &amp;, the function converts
those characters to <, >, or &, respectively. Use the Unescape XML VI to convert other
characters, such as ".

Inputs/Outputs
• xml string —

xml string is the XML string that includes the data you want to convert.

xml string must conform to the LabVIEW XML schema, including the case and order of tags in the
schema. If xml string does not conform to the schema, the function returns an error and value
contains the default value for the data type wired to type. If the VI containing the function
previously completed execution, value contains the value from the previous execution.

In xml string, this function accepts only the period (.) as a decimal separator. The function does
not recognize localized decimal separators. This restriction prevents errors when you use XML
strings on operating systems with different settings for the decimal separator.

© National Instruments 1729

 Functions

• type —

type is the data type to which you want to convert xml string.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• value —

value is the data type you specified in type and the data in xml string.

• error out —

error out contains error information. This output provides standard error out functionality.

Write to XML File

Writes a text string of XML data with accompanying header tags to a text file. Wire data
to the XML Input input to determine the polymorphic instance to use or manually
select the instance. All XML data must follow the standard LabVIEW XML schema.

• Write to XML File(string) VI

• Write to XML File(array) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

1730 ni.com
 Functions

Write to XML File(string) VI

Writes a text string of XML data with accompanying header tags to a text file. Wire data
to the XML Input input to determine the polymorphic instance to use or manually
select the instance. All XML data must follow the standard LabVIEW XML schema.

Inputs/Outputs
• XML File Path —

XML File Path is the path and filename to which you want to write XML data.

The filename must have a .xml extension. When you specify an empty path, a dialog box
prompts the user to specify an XML file.

• XML Input —

XML Input contains XML data to write to the file.

• XML Encoding —

XML Encoding specifies the encoding scheme for the XML file. LabVIEW supports ANSI and
Multibyte encoding schemes.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Standalone? (T) —

Standalone? specifies the value for the standalone attribute in the XML declaration.
Standalone? determines whether the document exists entirely on its own (TRUE), or depends on
other files (FALSE).

• XML File Path(duplicate) —

© National Instruments 1731

 Functions

XML File Path(duplicate) is the path of the file to which the VI writes data.

You can use this output to determine the file path that you selected through a dialog box. XML
File Path(duplicate) has a value of <Not A Path> if you cancelled the dialog box.

• XML String —

XML String contains the XML data that the VI writes to the specified file.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

Write to XML File(array) VI

Writes a text string of XML data with accompanying header tags to a text file. Wire data
to the XML Input input to determine the polymorphic instance to use or manually
select the instance. All XML data must follow the standard LabVIEW XML schema.

Inputs/Outputs
• XML File Path —

XML File Path is the path of the file to which the VI writes data.

1732 ni.com
 Functions

The filename must have a .xml extension. When you specify an empty path, a dialog box
prompts the user to specify an XML file.

• XML Input —

XML Input allows you to write multiple nodes of XML data to an XML file.

• XML Encoding —

XML Encoding specifies the encoding scheme for the XML file. LabVIEW supports ANSI and
Multibyte encoding schemes.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Standalone? (T) —

Standalone? specifies the value for the standalone attribute in the XML declaration.
Standalone? determines whether the document exists entirely on its own (TRUE), or depends on
other files (FALSE).

• XML File Path —

XML File Path is the path and filename to which you want to write XML data.

You can use this output to determine the file path that you selected through a dialog box. XML
File Path has a value of <Not A Path> if you cancelled the dialog box.

• XML String —

XML String contains the XML data that the VI writes to the specified file.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 1733

 Functions

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

Read From XML File

Reads and parses tags from a LabVIEW XML file. When you place this VI on the block
diagram, the polymorphic VI selector is visible. Use this selector to choose which
polymorphic instance to use. All XML data must follow the standard LabVIEW XML
schema.

• Read From XML File(array) VI

• Read From XML File(string) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

Read From XML File(array) VI

Reads and parses tags from a LabVIEW XML file. When you place this VI on the block
diagram, the polymorphic VI selector is visible. Use this selector to choose which
polymorphic instance to use. All XML data must follow the standard LabVIEW XML
schema.

1734 ni.com
 Functions

Inputs/Outputs
• XML File Path —

XML File Path is the path and filename from which you want to read XML data.

When you specify an empty path, a dialog box prompts the user to specify an XML file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• XML File Path(duplicate) —

XML File Path(duplicate) is the path of the file from which the VI reads data.

You can use this output to determine the file path that you selected through a dialog box. XML
File Path(duplicate) has a value of <Not A Path> if you cancelled the dialog box.

• XML Elements —

XML Elements returns the top-level XML tags found between the end of the </Version> and
</LVData> tags in an array of strings. You then can index the array and use the Unflatten From
XML function.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

Flatten and Unflatten XML.lvproj

Read From XML File(string) VI

Reads and parses tags from a LabVIEW XML file. When you place this VI on the block
diagram, the polymorphic VI selector is visible. Use this selector to choose which

© National Instruments 1735

 Functions

polymorphic instance to use. All XML data must follow the standard LabVIEW XML
schema.

Inputs/Outputs
• XML File Path —

XML File Path is the path and filename from which you want to read XML data.

When you specify an empty path, a dialog box prompts the user to specify an XML file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• XML File Path(duplicate) —

XML File Path(duplicate) is the path of the file from which the VI reads data.

You can use this output to determine the file path that you selected through a dialog box. XML
File Path(duplicate) has a value of <Not A Path> if you cancelled the dialog box.

• XML Elements —

XML Elements returns the top-level XML tags found between the end of the </Version> and
</LVData> tags in a single string. You then can wire this output to the Unflatten From XML
function.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Flatten and Unflatten XML\

1736 ni.com
 Functions

Flatten and Unflatten XML.lvproj

Escape XML
Converts special characters to XML syntax according to the LabVIEW XML schema.

The Flatten To XML function converts the characters <, >, or & to &lt;, &gt;, or
&amp;, respectively, but you must use this VI to convert other characters, such as ", to
XML syntax.

Inputs/Outputs
• XML String In —

XML String In is the XML string for which you want to convert special characters.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• XML String Out —

XML String Out is the XML string with special characters converted.

• error out —

error out contains error information. This output provides standard error out functionality.

Unescape XML
Converts the XML syntax for special characters back to the special characters
according to the LabVIEW XML schema.

© National Instruments 1737

 Functions

The Unflatten From XML function converts the characters &lt;, &gt;, or &amp; to <,
>, or &, respectively, but you must use this VI to convert other characters, such as
&quot;.

Inputs/Outputs
• XML String In —

XML String In is the XML string that contains the XML-formatted characters you want to convert.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• XML String Out —

XML String Out is the XML string with special characters.

• error out —

error out contains error information. This output provides standard error out functionality.

XML Parser

Use the XML Parser VIs and nodes to process XML documents using the XML parser.

The XML parser in LabVIEW is the Xerces 2.7 parser which uses a document object
model (DOM).

The VIs and nodes on this palette can return XML Parser error codes.

1738 ni.com
 Functions

Palette
Description
Object

Returns an XML parser session in LabVIEW. Use this VI each time you create a new XML
New
parser session.

Gets (reads) and/or sets (writes) properties of an XML reference. The node operates in the
Property same way as a standard Property Node.
Node
(XML) National Instruments recommends that you use the Close VI to close all the references
after using the XML parser classes.

Invoke
Invokes a method or action on an XML reference. The node operates in the same way as a
Node
standard Invoke Node.
(XML)

Closes a reference for all XML parser classes. You can use this polymorphic VI to close
Close refnums from the NamedNodeMap class, the NodeList class, the Implementation class,
or the Node class. The Node class encompasses all other XML classes.

Get First
Returns the first node within node in that matches the XPath expression. If this VI does
Matched
not find a match, node result is not a valid refnum.
Node

Get All
Matched Returns all the nodes within node in that match the XPath expression.
Nodes
Get Next
Non-
Returns the first sibling of the node in that is not of type Text_Node.
Text
Sibling
Get First
Non-
Returns the first child of the node in that is not of type Text_Node.
Text
Child

© National Instruments 1739

 Functions

Palette
Description
Object
Get
Node
Returns the combined values of Text_Node children that the node in node owns.
Text
Content

Opens an XML file and allows you to configure the XML parser to validate the file against a
schema or Document Type Definition (DTD).
Load
National Instruments recommends that you use the Close VI to close all the references
after using the XML parser classes.

Save Saves an XML document.

New
Returns an XML parser session in LabVIEW. Use this VI each time you create a new XML
parser session.

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• DOM document out —

DOM document out returns a reference to the new XML parser session.

• error out —

1740 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Property Node (XML)

Gets (reads) and/or sets (writes) properties of an XML reference. The node operates in
the same way as a standard Property Node.

National Instruments recommends that you use the Close VI to close all the references
after using the XML parser classes.

Inputs/Outputs
• reference —
reference is the refnum associated with an XML parser object that is already open.
• error in (no error) —
error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.
• reference out —
reference out returns reference unchanged.
• error out —
error out contains error information. This output provides standard error out functionality.
• Property —
property 1..n are examples of properties you want to get (read).

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Parse XML\Generate XML

String with Parser API.vi

© National Instruments 1741

 Functions

Invoke Node (XML)

Invokes a method or action on an XML reference. The node operates in the same way
as a standard Invoke Node.

Inputs/Outputs
• reference —
reference is the refnum associated with an XML parser object that is already open.
• error in (no error) —
error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.
• Method —
input 1..n are example input parameters of a method.
• reference out —
reference out returns reference unchanged.
• error out —
error out contains error information. This output provides standard error out functionality.
• Method —
return value is an example return value of a method.
• param —

output 1..n are example output parameters of a method.

Close
Closes a reference for all XML parser classes. You can use this polymorphic VI to close
refnums from the NamedNodeMap class, the NodeList class, the Implementation
class, or the Node class. The Node class encompasses all other XML classes.

1742 ni.com
 Functions

• Close Reference(NNMap) VI
• Close Reference(NdList) VI
• Close Reference(Impl) VI
• Close Reference(Node) VI

Close Reference(NNMap) VI
Closes a reference for all XML parser classes. You can use this polymorphic VI to close
refnums from the NamedNodeMap class, the NodeList class, the Implementation
class, or the Node class. The Node class encompasses all other XML classes.

Inputs/Outputs
• named node map —

named node map is the XML Parser NamedNodeMap class refnum that you want to close.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Close Reference(NdList) VI
Closes a reference for all XML parser classes. You can use this polymorphic VI to close
refnums from the NamedNodeMap class, the NodeList class, the Implementation
class, or the Node class. The Node class encompasses all other XML classes.

© National Instruments 1743

 Functions

Inputs/Outputs
• node list —

node list is the XML Parser NodeList class refnum that you want to close.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Close Reference(Impl) VI
Closes a reference for all XML parser classes. You can use this polymorphic VI to close
refnums from the NamedNodeMap class, the NodeList class, the Implementation
class, or the Node class. The Node class encompasses all other XML classes.

Inputs/Outputs
• implementation —

implementation is the XML Parser Implementation class refnum that you want to close.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following

1744 ni.com
 Functions

exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Close Reference(Node) VI
Closes a reference for all XML parser classes. You can use this polymorphic VI to close
refnums from the NamedNodeMap class, the NodeList class, the Implementation
class, or the Node class. The Node class encompasses all other XML classes.

Inputs/Outputs
• node —

node is the XML Parser Node class refnum that you want to close.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1745

 Functions

Get First Matched Node

Returns the first node within node in that matches the XPath expression. If this VI does
not find a match, node result is not a valid refnum.

Inputs/Outputs
• node in —

node in is a reference to an instance of XML Parser class Node. This VI uses node in as the context
node to evaluate the XPath expression.

• XPath expression —

XPath expression specifies the expression this VI uses to query node in for a match. Use XPath
syntax to define the XPath expression.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• node out —

node out contains the same reference as node in.

• node result —

node result returns a reference to the first node that matches XPath expression. If this VI does
not find a match, node result is not a valid refnum. You can use the Not a Number/Path/Refnum?
function to establish whether this VI finds a match.

• error out —

error out contains error information. This output provides standard error out functionality.

1746 ni.com
 Functions

Get All Matched Nodes

Returns all the nodes within node in that match the XPath expression.

Inputs/Outputs
• node in —

node in is a reference to an instance of XML Parser class Node. This VI uses node in as the context
node to evaluate the XPath expression.

• XPath expression —

XPath expression specifies the expression this VI uses to query node in for a match. Use XPath
syntax to define the XPath expression.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• node out —

node out contains the same reference as node in.

• node result array —

node result array returns an array of references to each node that matches XPath expression. If
this VI does not find a match, node result array is empty.

If you use a For Loop to process each node from node result array, consider using shift registers
instead of tunnels for other data you pass through the loop. Doing so avoids surprising behaviors
in case node result array is empty.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1747

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\XML\Parse XML\Parse XML String

for Multiple Nodes.vi

Get Next Non-Text Sibling

Returns the first sibling of the node in that is not of type Text_Node.

Inputs/Outputs
• node in —

node in is a reference to an instance of XML Parser class Node.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• node out —

node out contains the same reference as node in.

• sibling node —

sibling node contains a reference to the sibling.

• found sibling node? —

found sibling node? indicates whether the VI located a non-Text_Node sibling.

• error out —

1748 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Get First Non-Text Child

Returns the first child of the node in that is not of type Text_Node.

Inputs/Outputs
• node in —

node in is a reference to an instance of XML Parser class Node.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• node out —

node out contains the same reference as node in.

• child node —

child node contains a reference to the child.

• found child node? —

found child node? indicates whether the VI located a non-Text_Node child.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1749

 Functions

Get Node Text Content

Returns the combined values of Text_Node children that the node in node owns.

Inputs/Outputs
• node in —

node in is a reference to an instance of XML Parser class Node.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• node out —

node out contains the same reference as node in.

• node text —

node text contains the combined values of the Text_Node children.

• error out —

error out contains error information. This output provides standard error out functionality.

Load
Opens an XML file and allows you to configure the XML parser to validate the file
against a schema or Document Type Definition (DTD).

National Instruments recommends that you use the Close VI to close all the references
after using the XML parser classes.

1750 ni.com
 Functions

The VI contains information about errors that the XML parser encounters while parsing
the document.

• Load XML File VI

• Load XML String VI

Load XML File VI

Opens an XML file and allows you to configure the XML parser to validate the file
against a schema or Document Type Definition (DTD).

National Instruments recommends that you use the Close VI to close all the references
after using the XML parser classes.

The VI contains information about errors that the XML parser encounters while parsing
the document.

Inputs/Outputs
• validate on load (Auto) —

validate on load specifies the validation scheme that the XML parser uses. The default is Auto,
which turns on validation only if the parser detects an internal or external DTD subset.

You also can select Always, which turns on validation, or Never, which turns off validation.

• preserve whitespace (True) —

© National Instruments 1751

 Functions

preserve whitespace specifies whether a validating parser includes ignorable whitespaces as

Text Nodes. The default is TRUE.

If you select FALSE, the parser discards ignorable whitespaces and does not add Text Nodes to
the DOM tree. If you select FALSE, you must provide a valid DTD definition for the Preserve
Whitespace option to correctly discard ignorable whitespaces. If the XML document is invalid or
has no schema, the Preserve Whitespace option is ignored.

• path to XML document —

path to XML document contains the location of the XML document you want to load into the
XML parser.

Note The XML document must include an XML prolog with a valid encoding value. If
the encoding value is incorrect or missing, this function might fail to parse the XML
document.

• process namespaces (False) —

process namespaces disables namespace processing for the XML parser when set to FALSE, the
default. When set to TRUE, the XML parser enforces the constraints and rules that the
NameSpace specification contains.

• process schema (False) —

process schema disables schema processing for the XML parser when set to FALSE, the default. If
you set the control to TRUE, you must set process namespaces to TRUE.

• load external DTD (True) —

load external DTD specifies whether the XML parser can load external DTDs. The default is TRUE.

LabVIEW loads the schema specified in the metadata of the XML file. If you set validate on load
to Always or Auto, the parser ignores this input and always loads the DTD.

In the XML file, specify the external schema you want to use in one of the following metadata
attributes:
• xsi:schemaLocation—Use this attribute if you define the targetNamespace attribute in the
metadata of the XML file.
• xsi:noNamespaceSchemaLocation—Use this attribute if you do not define the
targetNamespace attribute in the metadata of the XML file.
Refer to TestConfiguration.xml in the examples\File IO\XML\Parse XML\
support directory for an example of specifying a schema in an XML file.

1752 ni.com
 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• schema full checking (False) —

schema full checking specifies whether the XML parser runs full or partial schema constraint
checking. The default is FALSE, which configures the XML parser to run partial constraint
checking.

• DOM document out —

DOM document out returns a reference to the new XML parser session.

• parse errors —

parse errors contains information on errors the XML parser found when it parsed the document,
including problems the parser encountered when validating the document against the schema.

• error out —

error out contains error information. This output provides standard error out functionality.

Load XML String VI

Opens an XML file and allows you to configure the XML parser to validate the file
against a schema or Document Type Definition (DTD).

National Instruments recommends that you use the Close VI to close all the references
after using the XML parser classes.

The VI contains information about errors that the XML parser encounters while parsing
the document.

© National Instruments 1753

 Functions

Inputs/Outputs
• validate on load (Auto) —

validate on load specifies the validation scheme that the XML parser uses. The default is Auto,
which turns on validation only if the parser detects an internal or external DTD subset.

You also can select Always, which turns on validation, or Never, which turns off validation.

• preserve whitespace (True) —

preserve whitespace specifies whether a validating parser includes ignorable whitespaces as

Text Nodes. The default is TRUE.

If you select FALSE, the parser discards ignorable whitespaces and does not add Text Nodes to
the DOM tree. If you select FALSE, you must provide a valid DTD definition for the Preserve
Whitespace option to correctly discard ignorable whitespaces. If the XML document is invalid or
has no schema, the Preserve Whitespace option is ignored.

• XML string —

XML string is the XML string that includes the data you want to parse.

Note The XML string must include an XML prolog with a valid encoding value. If the
encoding value is incorrect or missing, this function might fail to parse the XML string.

• process namespaces (False) —

process namespaces disables namespace processing for the XML parser when set to FALSE, the
default. When set to TRUE, the XML parser enforces the constraints and rules that the
NameSpace specification contains.

• process schema (False) —

process schema disables schema processing for the XML parser when set to FALSE, the default. If
you set the control to TRUE, you must set process namespaces to TRUE.

1754 ni.com
 Functions

• load external DTD (True) —

load external DTD specifies whether the XML parser can load external DTDs. The default is TRUE.

LabVIEW loads the schema specified in the metadata of the XML file. If you set validate on load
to Always or Auto, the parser ignores this input and always loads the DTD.

In the XML file, specify the external schema you want to use in one of the following metadata
attributes:

• xsi:schemaLocation—Use this attribute if you define the targetNamespace attribute in the

metadata of the XML file.
• xsi:noNamespaceSchemaLocation—Use this attribute if you do not define the
targetNamespace attribute in the metadata of the XML file.

Refer to TestConfiguration.xml in the examples\File IO\XML\Parse XML\

support directory for an example of specifying a schema in an XML file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• schema full checking (False) —

schema full checking specifies whether the XML parser runs full or partial schema constraint
checking. The default is FALSE, which configures the XML parser to run partial constraint
checking.

• DOM document out —

DOM document out returns a reference to the new XML parser session.

• parse errors —

parse errors contains information on errors the XML parser found when it parsed the document,
including problems the parser encountered when validating the document against the schema.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1755

 Functions

Save
Saves an XML document.

Inputs/Outputs
• DOM document in —

DOM document in contains a reference to the XML parser session you want to save.

• XML file path —

XML file path specifies the path where you want to save the file.

• overwrite file (True) —

overwrite file specifies whether you want the VI to overwrite an existing file with the same
name. The default is TRUE, which overwrites an existing file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• DOM document out —

DOM document out contains the same reference as DOM document in.

• XML file path out —

XML file path out contains the path where the VI saved the file.

• error out —

error out contains error information. This output provides standard error out functionality.

1756 ni.com
 Functions

Waveform File I/O

Use the Waveform File I/O VIs to write waveform data to and read waveform data from
files.

The VIs on this palette can return waveform error codes.

Palette
Description
Object

Creates a new file or appends to an existing file, writes the specified number of
Write
records to the file, then closes the file and checks for errors. Each record is an array of
Waveforms
waveforms. Wire data to the Waveform input to determine the polymorphic instance
to File
to use or manually select the instance.

Read Opens a file created with the Write Waveforms to File VI and reads one record of the
Waveforms file. Each record might contain one or more separate waveforms. To retrieve all
from File records in the file, call this VI in a loop until the end of the file is reached.

Export
Waveforms Converts a waveform to a text string and writes the string to a new byte stream file or
to appends the string to an existing file. Wire data to the waveforms input to determine
Spreadsheet the polymorphic instance to use or manually select the instance.
File

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Waveform\Waveform - Write Waveforms to

File.vi

© National Instruments 1757

 Functions

Advanced File Functions

Use the Advanced File VIs and functions to manipulate files, directories, and paths.

Palette
Description
Object
Get File
Returns the position of the current file mark of the file identified by refnum relative
Position
to the beginning of the file.
Function
Get File Size
Gets the file size of file. This function does not work for files inside an LLB.
Function
Get
Returns the owner, group, and permissions of the file or directory specified by path.
Permissions
This function does not work for files inside an LLB.
Function
Get Type and
Reads the type and creator of the file specified by path. type and creator are four-
Creator
character strings. This function does not work for files inside an LLB.
Function
Preallocated
Reads binary data from a file and places the data into an array that you have already
Read from
allocated without incurring a copy of the data. Unlike the Read from Binary File
Binary File
function, this function avoids run-time memory allocations.
Function

File Dialog Displays a dialog box with which you can specify the path to a file or directory.

Set File
Moves the position of the current file mark of the file identified by refnum to the
Position
position indicated by offset (in bytes) according to the mode in from.
Function
Set File Size Sets the file size of file by setting the end-of-file marker to size bytes from the
Function beginning of the file. This function does not work for files inside an LLB.
Set
Sets the owner, group, and permissions of the file or directory specified by path.
Permissions
This function does not work for files inside an LLB.
Function
Set Type and Sets the type and creator of the file specified by path. type and creator are four-

1758 ni.com
 Functions

Palette
Description
Object
Creator character strings. This function does not work for files inside an LLB. Only macOS
Function supports setting the type and creator of files.

Opens a path to a file or directory in (Windows) Windows Explorer, (macOS) the

Show in File Finder, or (Linux) a file system browser depending on the current platform. If you
System specify a path to a file that is inside an LLB or a packed project library, this VI opens
the path to the LLB or the packed project library.

Checks if a filename is valid on different platforms. This VI checks filenames against

Is Name only desktop platforms that support LabVIEW, which are Windows, macOS, and
Multiplatform Linux. You can choose to check the filename against all possible platforms or
against the current platform.

Create File
Creates a file and appends an incrementing number suffix to the filename if the file
with
already exists at a specified path. If the file does not exist, this VI creates the file
Incrementing
without appending an incrementing number suffix to the filename.
Suffix

Moves the file or directory that you specify in source path to the location that you
Move specify in target path. If you move a directory, this function moves all the contents
Function of the directory recursively to the new location. You cannot use this function to
move files into or out of an LLB.
Copies the file or directory that you specify in source path to the location that you
Copy specify in target path. If you copy a directory, this function copies all its contents
Function recursively to the new location. You cannot use this function to copy files into or out
of an LLB.
Delete Deletes the file or directory specified by path. This function does not work for files
Function inside an LLB.
Flush File Writes all buffers of the file identified by refnum to disk and updates the directory
Function entry of the file associated with refnum.
Deny Access Reopens the instance of the file specified by refnum to temporarily change what
Function read or write access is denied to other refnums, VIs, or applications.
Returns information about the file or directory specified by path, including its size,
File/Directory
its last modification date, whether it is a directory, whether it is a shortcut, and the
Info Function
resolved path if the file or directory is a shortcut. This function does not work for

© National Instruments 1759

 Functions

Palette
Description
Object
files inside an LLB.
Returns information about the volume containing the file or directory specified by
Get Volume
path, including the total storage space provided by the volume and the amount free
Info Function
in bytes.
Create Folder
Creates the appropriate folder specified by path.
Function
Returns two arrays of strings listing the names of all files and folders found in path,
List Folder
filtering both arrays based upon pattern and filtering the filenames array based
Function
upon the specified datalog type.

Check if File
Checks whether a file or folder exists on disk at a specified path. This VI works with
or Folder
standard files and folders as well as files in LLB files.
Exists

Recursive File
Lists the contents of a folder or LLB.
List

Path To
String Converts path into a string describing a path in the standard format of the platform.
Function
String To
Converts a string, describing a path in the standard format for the current platform,
Path
to a path.
Function
Path to Array
of Strings Converts a path into an array of strings and indicates whether the path is relative.
Function
Array of
Strings to
Converts an array of strings into a relative or absolute path.
Path
Function
Refnum to
Path Returns the path associated with the specified refnum.
Function
Path Type Returns the type of the specified path, indicating whether it is an absolute, relative,
Function or <Not A Path>.

1760 ni.com
 Functions

Palette
Description
Object

Compares Path 1 to Path 2 and returns a relative path between the two paths, the
Compare
common path between the two paths, and a Boolean that indicates whether the
Two Paths
paths are on the same path hierarchy level.

Get File
Returns the file extension, without the period (.), of a file you specify.
Extension

File Computes the message digest on the contents of a file. You must manually select
Checksum the polymorphic instance you want to use.

Generate
Returns a unique file path to the temporary directory. This VI only returns a path. It
Temporary
does not create the temporary file.
File Path

Use the Datalog functions to open and close datalog files, read from and write to
Datalog datalog files, get and set datalog file positions, and get and set the number of
datalog records.

Packed
Use the Packed Library VIs to get and return data from a packed project library.
Library

Create
Directory Creates a directory and any parent directories it requires to exist.
Recursive
Create File
and
Creates a file at a specified path and any folders within that path that do not exist.
Containing
Folders

Get File Position Function

Returns the position of the current file mark of the file identified by refnum relative to
the beginning of the file.

© National Instruments 1761

 Functions

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file whose file mark you want to move.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum unchanged.

• offset (in bytes) —

offset (in bytes) indicates the new location of the file mark relative to the beginning of the file
(zero-based).

• error out —

error out contains error information. This output provides standard error out functionality.

Get File Size Function

Gets the file size of file. This function does not work for files inside an LLB.

Inputs/Outputs
• file —

file can be a refnum or file path.

1762 ni.com
 Functions

If it is a file path, this node opens the file specified by the file path.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the refnum of the file that the function read. You can wire this output to another
file function, depending on what you want to do with the file. The default is to close the file if it is
referenced by a file path. If file is a refnum or if you wire refnum out to another function,
LabVIEW assumes that the file is still in use until you close it.

• size (in bytes) —

size (in bytes) is the size of the file in bytes.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Permissions Function

Returns the owner, group, and permissions of the file or directory specified by path.
This function does not work for files inside an LLB.

Inputs/Outputs
• path —

path specifies the file or directory whose access rights you want to change.

• error in —

error in describes error conditions that occur before this node runs. This input provides

© National Instruments 1763

 Functions

standard error in functionality.

• permissions —

permissions contains the current permissions setting for the file or directory after this function
executes.

• path out —

path out returns path unchanged.

• owner —

owner contains the current owner setting for the file or directory after this function executes.

• group —

group contains the current group setting for the file or directory after this function executes.

• error out —

error out contains error information. This output provides standard error out functionality.

Refer to Setting Permissions for more information about the permissions parameter.

(Windows) This function returns empty strings for owner and group because Windows
does not support owners and groups.

(macOS) If path refers to a file, this function returns empty strings for owner and group
because macOS does not support owners or groups for files.

Get Type and Creator Function

Reads the type and creator of the file specified by path. type and creator are four-
character strings. This function does not work for files inside an LLB.

If the specified file has a name ending with characters that LabVIEW recognizes, such
as .vi for the LVIN file type and .llb for the LVAR file type, this function returns that
type in type and LBVW in creator. If the specified file is not a known LabVIEW file type,
this function returns ???? in type and creator.

1764 ni.com
 Functions

Inputs/Outputs
• path —

path specifies the file or directory whose type or creator you want to read.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

path out returns path unchanged.

• type —

type contains the current type of the file after this function executes.

If no error occurs, this function returns the type of the specified file in type. If an error occurs,
error indicates the type of error and type is an empty string.
• creator —

creator contains the current creator of the file after this function executes.

If no error occurs, this function returns the creator of the specified file in creator. If an error
occurs, error indicates the type of error and creator is an empty string.
• error out —

error out contains error information. This output provides standard error out functionality.

type can return the values for LabVIEW files listed in the table below.

LabVIEW File Type type Value

Control LVCC
.log LVDL

© National Instruments 1765

 Functions

LabVIEW File Type type Value

LabVIEW Class CLIB
LabVIEW Project LVPJ
Library LIBR
LLB LVAR
Palette LMNU
Template Control sVCC
Template VI sVIN
Xcontrol LVXC
VI LVIN

The type parameter can also return some platform-specific strings.

Preallocated Read from Binary File Function

Reads binary data from a file and places the data into an array that you have already
allocated without incurring a copy of the data. Unlike the Read from Binary File
function, this function avoids run-time memory allocations.

The performance of this function depends on the array you preallocate.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• refnum in —

refnum in specifies the file refnum associated with the file you want to read.

• data in —

1766 ni.com
 Functions

data in specifies the array in which to place data. This function attempts to read as many data
elements as the array holds. Refer to the support table for information about the arrays and data
types this function supports.

• byte order (0:big-endian, network order) —

byte order sets the endian form of the resulting data. Byte order, or endian form, indicates
whether integers are represented in memory from most-significant byte to least-significant byte
or vice versa. The function must read the data in the same byte order that the data was written.

Note This function requires that you set the byte order parameter to match the
native byte order of the host computer running LabVIEW. If the computer is big
endian, choose either native, host order or big-endian, network order> endian form.
If the computer is little endian, choose either native, host order or little-endian
endian form.

big-endian, network order (default)—The most-significant byte occupies the lowest memory
0 address. This endian form is used on PowerPC platforms such as VxWorks. This endian-form
also is used when reading data written on a different platform.
native, host order—Uses the byte-ordering format of the host computer. This endian form
1
increases read and write speed.
little-endian—The least-significant byte occupies the lowest memory address. This endian
2
form is used on Windows, macOS, and Linux.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the refnum of the file that the function read. You can wire this output to another
file function.

• data out —

data out contains the data read from the file. This output does not resize to include only valid
data. If LabVIEW reaches the end of the file before the data in array is full, then the array contains
some invalid elements. Use the num elements read output to determine the exact amount of
valid data in data out. If LabVIEW does not reach the end of the file before the data in array is
full, LabVIEW leaves the file pointer where the read finished so that the next read starts where

© National Instruments 1767

 Functions

the last read left off.

• num elements read —

num elements read returns the total number of elements in the data in array replaced with data
from the file.

• error out —

error out contains error information. This output provides standard error out functionality.

The following block diagram shows an example of how this function works with a pre-
allocated array. Each time the Preallocated Read from Binary File function executes,
LabVIEW places the data from file in the same array.

Preallocated Read from Binary File Support

This function provides different levels of support for arrays you wire to place data from
file:

Fully supported. Because the function does not require a new allocation, it is
probably faster than the Read from Binary File function.

Supported. Because the function requires a new allocation and copy, it is probably
slower than the Read from Binary File function.

Not accepted by the function.

The following table describes support when the array you wire to data in is a particular
array or array slice that contains a particular data type.

1768 ni.com
 Functions

Contiguous Array Noncontiguous Array

Data Type Array
Slice Slice1
Integers
Single-precision, floating-point numeric
Double-precision, floating-point numeric
Extended-precision, floating-point numeric²
Complex single-precision, floating-point
numeric
Complex double-precision, floating-point
numeric
Complex extended-precision, floating-point
numeric²
Fixed-point numeric²
Boolean
String
All other data types

Note

1. LabVIEW must make a memory copy of a noncontiguous array slice.

Therefore, the Preallocated Read from Binary File function is not faster
than the Read from Binary File function if you wire a noncontiguous array
slice to data in.
2. The Preallocated Read from Binary File function accepts extended
precision, complex extended precision, and fixed-point data. However,
this function allocates memory for a new copy with these data types, like
the Read from Binary File function, because it cannot put the data in an
existing allocation.

This function also fully supports each of the data types from the table as scalar values
that are not contained in arrays.

© National Instruments 1769

 Functions

File Dialog

Displays a dialog box with which you can specify the path to a file or directory.

You can use this dialog box to select existing files or directories or to select a location
and name for a new file or directory.

(macOS) This VI does not recognize macOS-specific means of specifying the default
application for a file. However, you can use the pattern input to specify a file type for
files that include an extension to the filename.

Dialog Box Options

Option Description

The user can select one or more files. When you de-select this option, the options for the
types of files or folders the user can select appear dimmed.

• files or folders—
Contains the following options:
Limit ◦ File—The user can select only a file.
selection ◦ Folder—The user can select only a folder.
to single ◦ File or folder—The user can select either a file or a folder.
item • new or existing—
Contains the following options:
◦ Existing—The user can select only an existing file or folder.
◦ New—The user only can enter the name of a new file or folder.
◦ New or existing—The user can select an existing file or folder or create a new
file or folder.

Allow
selection Specifies that you can select a file from an LLB or a packed library. If this checkbox does
of files in

1770 ni.com
 Functions

Option Description

not contain a checkmark, you can select an LLB or a packed library but you cannot
select a file in an LLB or a packed library.

LLBs and Note To select an LLB or packed library using the File Dialog Express VI, you
packed can remove the checkmark from the Allow selection of files in LLBs and
project packed project libraries checkbox and select the LLB or packed library from
libraries the file dialog box. You also can place a checkmark in the Allow selection of
files in LLBs and packed project libraries checkbox, select the Files or
Folders option button, choose an LLB or packed library from the file dialog
box, and select the second folder icon from the file list in the second file
dialog box that appears.

Inputs/Outputs
• button label —

Label to display on the OK or Current Directory button in the file dialog box. If you configure the
Express VI to allow the user to select directories, use this input to specify a label for the Current
Directory button. If the configuration does not allow the user to select directories, use this input
to specify a label for the OK button.

For example, if you select Files only in the configure dialog box, the user must select an existing
file to which to append data, so you might want to wire Append to button label.

If button label is longer than the width of the button, the file dialog box does not display the
entire label. For example, in an English version of Windows, the button is approximately 11
characters wide.

• pattern (all files) —

Restricts the files displayed in the dialog box to those whose name matches pattern (all files).
pattern (all files) does not restrict the directories displayed.

The pattern matching in this VI is similar to the matching used in matching wildcards in Windows
and Linux filenames. If you specify characters other than the question mark character (?) or the
asterisk character (*), the VI displays only files or directories that contain those characters. You
can use the question mark character (?) to match any single character. You can use the asterisk
character (*) to match any sequence of zero or more characters.

© National Instruments 1771

 Functions

For example, a pattern (all files) of *.vi;test*.llb returns matches for any file with a .vi
extension and any file whose filename begins with test and has a .llb extension.

To match multiple patterns, use a semicolon ( ; ) to separate the patterns. White space, such as
blanks, tabs, and carriage returns, are taken literally. Avoid using white spaces unless they are
part of the extension pattern. For example, if you use *.html;*.doc, the dialog box displays
all files that end with .html and .doc. If you use *.html; *.doc, the dialog box displays
only files that end with .html.

• start path —

Path of the directory whose contents LabVIEW initially displays in the dialog box.

If start path is valid, but does not refer to an existing directory, LabVIEW strips names from the
end of the path until the path is a valid directory path or an empty path. If start path is invalid or
unwired, the last directory viewed in a file dialog box initially appears in the dialog box.

• default name —

Name you want to appear as the initial file or directory name in the dialog box.

The default is an empty string.

• error in —

Describes error conditions that occur before this node runs.

• prompt —

Custom message that appears as the title of the file dialog box. (Windows and Linux) The default
dialog box title is Choose or Enter Path of File. (macOS) The default dialog box title is Select File
or Create New File.

• pattern label —

Label to display in the file dialog box next to the custom pattern.

If you do not wire this input or it contains an empty string, the default label next to any custom
pattern is Custom Pattern. If you do not wire a string to pattern, LabVIEW ignores this input.

• error out —

Contains error information. This output provides standard error out functionality.

1772 ni.com
 Functions

• selected path —

Full path to the file or directory selected using this dialog box.

If you cancel the dialog box, this VI sets selected path to <Not A Path>. This output is
available if you place a checkmark in the Limit selection to single item checkbox in the
Configure File Dialog dialog box.

• exists —

Is TRUE if selected path specifies an existing file or directory.

• cancelled —

Is TRUE if you cancel the dialog box.

• selected paths —

Contains the full path names to the files or directories selected using this dialog box. This output
is available if you do not place a checkmark in the Limit selection to single item in the
Configure File Dialog dialog box.

Components

Specifies that you can select a file from an LLB or a packed library. If this checkbox
does not contain a checkmark, you can select an LLB or a packed library but you
cannot select a file in an LLB or a packed library.

The user can select one or more files. When you de-select this option, the options for
the types of files or folders the user can select appear dimmed.

Contains the following options:

• Existing—The user can select only an existing file or folder.

• New—The user only can enter the name of a new file or folder.
• New or existing—The user can select an existing file or folder or create a new file or
folder.

Contains the following options:

• File—The user can select only a file.

© National Instruments 1773

 Functions

• Folder—The user can select only a folder.

• File or folder—The user can select either a file or a folder.

Set File Position Function

Moves the position of the current file mark of the file identified by refnum to the
position indicated by offset (in bytes) according to the mode in from.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file whose file mark you want to move.

• offset (in bytes) (0) —

offset (in bytes) specifies how far from the location specified by from to set the file mark.

• from (0:start) —

from, together with offset (in bytes), specifies where to set the file mark. If you wire offset (in
bytes), from defaults to 0, and the offset is relative to the beginning of the file. If you do not wire
offset (in bytes), offset (in bytes) defaults to 0, from defaults to 2, and the operation starts at the
current file mark.

start—Sets the file mark offset (in bytes) bytes from the beginning of the file. If from is 0, offset
0
(in bytes) should be positive or 0, which sets the file mark at the beginning of the file.
end—Sets the file mark offset (in bytes) bytes from the end of the file. If from is 1, offset (in
1
bytes) should be negative or 0, which sets the file mark at the end of the file.
2 current—Sets the file mark offset (in bytes) bytes from the current file mark.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

1774 ni.com
 Functions

refnum out returns refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

Set File Size Function

Sets the file size of file by setting the end-of-file marker to size bytes from the
beginning of the file. This function does not work for files inside an LLB.

Inputs/Outputs
• file —

file can be a refnum or file path.

If it is a file path, this node opens the file specified by the file path.
• size (in bytes) —

size (in bytes) is the size of the file in bytes.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the refnum of the file that the function read. You can wire this output to another
file function, depending on what you want to do with the file. The default is to close the file if it is
referenced by a file path. If file is a refnum or if you wire refnum out to another function,
LabVIEW assumes that the file is still in use until you close it.

• error out —

© National Instruments 1775

 Functions

error out contains error information. This output provides standard error out functionality.

Set Permissions Function

Sets the owner, group, and permissions of the file or directory specified by path. This
function does not work for files inside an LLB.

Inputs/Outputs
• permissions —

permissions specifies the new permissions setting for the file or directory.

Refer to Setting Permissions for more information about how to define the permissions you
want to set.
• path —

path specifies the file or directory whose access rights you want to change.

• new owner —

new owner specifies the new owner for the file or directory.

If new owner is an empty string, the VI does not set the owner.
• new group —

new group specifies the new group for the file or directory.

If new group is an empty string, the VI does not set the group.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

1776 ni.com
 Functions

path out returns path unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

If you do not specify new owner, new group, or permissions, this function returns the
current settings unchanged.

(Windows) This function ignores new owner and new group because Windows does
not support owners and groups.

(macOS) If path refers to a file, this function ignores new owner and new group
because macOS does not support owners or groups for files.

Set Type and Creator Function

Sets the type and creator of the file specified by path. type and creator are four-
character strings. This function does not work for files inside an LLB. Only macOS
supports setting the type and creator of files.

Inputs/Outputs
• path —

path specifies the file or directory whose type or creator you want to read.

• type (no change) —

type is the type of the specified file.

If type is a string other than four characters, an error occurs.

• creator (no change) —

© National Instruments 1777

 Functions

creator is the creator of the specified file.

If creator is a string other than four characters, an error occurs.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

path out returns path unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Show in File System

Opens a path to a file or directory in (Windows) Windows Explorer, (macOS) the Finder,
or (Linux) a file system browser depending on the current platform. If you specify a
path to a file that is inside an LLB or a packed project library, this VI opens the path to
the LLB or the packed project library.

Inputs/Outputs
• file or directory path —

file or directory path specifies the path to a file or directory.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

1778 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Is Name Multiplatform

Checks if a filename is valid on different platforms. This VI checks filenames against

only desktop platforms that support LabVIEW, which are Windows, macOS, and Linux.
You can choose to check the filename against all possible platforms or against the
current platform.

Inputs/Outputs
• filename —

filename specifies the filename to check.

• filename must be valid on all platforms (F) —

filename must be valid on all platforms specifies whether to check if the specified filename is
valid on all possible platforms. If this input is TRUE, the VI checks the filename against all
possible platforms. If this input is FALSE, the VI checks the filename against only the current
platform. The default is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• suggested filename —

suggested filename returns the filename that you specified if the filename is valid. If the
specified filename is invalid, this output transforms the specified filename into a valid filename
by replacing invalid characters with hyphens or removing ending periods.

• filename had conflict —

© National Instruments 1779

 Functions

filename had conflict returns whether the specified filename is valid on any possible platform or
the current platform. If filename must be valid on all platforms is TRUE, this output returns
TRUE if the specified filename is invalid on any possible platform. If filename must be valid on
all platforms is FALSE, this output returns TRUE if the specified filename is invalid on the current
platform.

• filename not crossplatform —

filename not crossplatform returns whether the specified filename is invalid on any possible
platform. This output returns TRUE if the specified filename is invalid on any possible platform.

• error out —

error out contains error information. This output provides standard error out functionality.

• problem description —

problem description returns the problem details if the specified filename is invalid on any
possible platform. This output lists reasons why the specified filename is considered invalid on
one or multiple platforms.

This VI checks if a filename is valid on different platforms according to the following

rules:

• (Windows) The following characters are invalid: \, /, :, *, ?, ", <, >, and |.
• (Windows) Filenames cannot end with a period (.).
• (macOS) The colon (:) is an invalid character.
• (Linux) The slash (/) is an invalid character.

The Is Name Multiplatform does not support multibyte characters. To check if a

filename with multibyte characters is valid, use Is Name Multiplatform_Allow
Multibyte.vi located in labview\vi.lib\Utility\Multibyte.

Create File with Incrementing Suffix

Creates a file and appends an incrementing number suffix to the filename if the file
already exists at a specified path. If the file does not exist, this VI creates the file
without appending an incrementing number suffix to the filename.

1780 ni.com
 Functions

Inputs/Outputs
• format string (" (%d)") —

format string specifies how to convert the file path into a string. format string must contain
exactly one decimal format code (%d). The default is " (%d)".

• file path —

file path specifies the path to the file you want to create. You must specify an absolute path. If
you specify an empty or relative path, this VI returns an error.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• disable buffering (F) —

disable buffering specifies if the file opens without buffering. The default is FALSE.

If you want to read or write a data file to a Redundant Array of Independent Disks (RAID),
consider opening the file without buffering to speed up data transfers. To disable buffering, wire
a TRUE value to the disable buffering input.

Note If you have a small amount of data to transfer, you might not notice a
difference if you disable buffering.

(macOS and Linux) LabVIEW ignores this input.

• refnum out —

refnum out returns the reference number of the file this VI creates.

• actual path —

actual path returns the path to the file this VI creates.

© National Instruments 1781

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

The following table displays examples of how this VI uses format string to convert file
path and to return actual path.

Format
File Path Actual Path Description
String
The %d in format string specifies that the VI appends an
" (%d)" C:\test.txt C:\test (1).txt incrementing number starting with 1 to the filename before the
period (.).
The 4 in format string specifies that the suffix after the filename
"%4d" C:\test.txt C:\test 1.txt
and before the period (.) has a width of 4.

Move Function

Moves the file or directory that you specify in source path to the location that you
specify in target path. If you move a directory, this function moves all the contents of
the directory recursively to the new location. You cannot use this function to move files
into or out of an LLB.

Inputs/Outputs
• prompt (Choose or enter target path for move) —

prompt is the message that appears above the list of files and directories, or folder, in the file
dialog box.

• source path —

source path specifies an absolute path to the file or directory on which you want to operate.

1782 ni.com
 Functions

If you specify an empty or relative path, this function returns an error.

• target path (use dialog) —

target path is the new absolute path for the file or folder on which you want to operate,
including the new file or folder name.

You must have write permission for the file or directory that you specify in target path;
otherwise, this function does not move the file or directory and returns an error.

Tip Use the Set Permissions function to set the permissions for a file or directory.

You must ensure the target path exists before running this function. If the last component of the
target path does not exist, this function renames the file or folder you specified in the source
path to this component name and moves the file or folder to the target location. See the
examples below for details. If target path is empty (default), the function displays a dialog box
from which you can select a file or folder. If you specify an empty or relative path, this function
returns an error.

Example: moving the source folder on C drive to the dest folder on D drive.

Input/
Value Notes
Output
source
C:\source —
path
target
D:\dest —
path
new D:\dest\ If the dest folder in target path exists, this function moves the source
path source folder to the dest folder.
If the dest folder in target path does not exist, this function renames the
new
D:\dest source folder to dest and then moves all the source folder contents to
path
the dest folder.

Example: moving the test.txt file under C:\source to the dest folder on D drive.

Input/
Value Notes
Output
source C:\source\
—
path test.txt
target
D:\dest —
path
new D:\dest\ If the dest folder in target path exists, this function moves the

© National Instruments 1783

 Functions

Input/
Value Notes
Output
path test.txt test.txt file to the dest folder.
new If the dest folder in target path does not exist, this function renames the
D:\dest
path test.txt file to dest and then moves this file to D drive.

• overwrite (F) —

overwrite determines whether the function replaces existing files or folders in the target path. If
you overwrite a folder that contains unique files, LabVIEW moves those files to the new folder.
(macOS and Linux) LabVIEW does not overwrite read-only files, even if you set this parameter to
TRUE.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• new path —

new path specifies the new location of the file or directory. If the operation is unsuccessful, this
function sets new path to <Not A Path>.

• cancelled —

cancelled is TRUE if you cancel the file dialog box.

Otherwise, cancelled is FALSE, even if this function returns an error.

• error out —

error out contains error information. This output provides standard error out functionality.

Copy Function

Copies the file or directory that you specify in source path to the location that you
specify in target path. If you copy a directory, this function copies all its contents
recursively to the new location. You cannot use this function to copy files into or out of
an LLB.

1784 ni.com
 Functions

Inputs/Outputs
• prompt (Choose or enter target path for copy) —

prompt is the message that appears above the list of files and directories, or folder, in the file
dialog box.

• source path —

source path specifies an absolute path to the file or directory on which you want to operate. If
you specify an empty or relative path, this function returns an error.

• target path (use dialog) —

target path is the new absolute path for the file or folder on which you want to operate,
including the new file or folder name.

If target path is empty (default), the function displays a dialog box from which you can select a
file or folder. If you specify an empty or relative path, this function returns an error. cancelled is
TRUE if you cancel the dialog box.

• overwrite (F) —

overwrite determines whether the function replaces existing files or folders in the target path. If
you overwrite a folder that contains unique files, LabVIEW moves those files to the new folder.
(macOS and Linux) LabVIEW does not overwrite read-only files, even if you set this parameter to
TRUE.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• new path —

new path specifies the new location of the file or directory.

If the operation is unsuccessful, this function sets new path to <Not A Path>.

• cancelled —

© National Instruments 1785

 Functions

cancelled is TRUE if you cancel the file dialog box.

Otherwise, cancelled is FALSE, even if this function returns an error.

• error out —

error out contains error information. This output provides standard error out functionality.

This function copies the original file or directory and renames the copy with the name
that you specify in the last element of the target path. If target path is the path to an
existing file, this function returns a Duplicate Path error. If target path is the path to an
existing directory, the function places the new file or directory inside the existing
directory using the original file or directory name.

For example, if you copy the directory c:\app to d:\app2, the function creates a
new directory d:\app2 with the same contents as c:\app. The second time you
copy the directory, the function creates a new subdirectory d:\app2\app and places
the contents of app there. The third time you copy the directory, the function returns a
Duplicate Path error.

This function also returns an error if the target path is an invalid path, such as if the
specified parent directory is not valid.

Note This function does not automatically append file extensions, such as
.txt, to filenames when it copies or moves files. You must explicitly include
the extension as a part of the new filename that you specify in target path.

If you do not have write permission for the file or directory that you specify in target
path, this function does not copy the file or directory and returns an error. Use the Set
Permissions function to set the permissions for a file or directory.

Delete Function

Deletes the file or directory specified by path. This function does not work for files
inside an LLB.

1786 ni.com
 Functions

Inputs/Outputs
• prompt (Delete) —

prompt is the message that appears above the list of files and directories, or folder, in the file
dialog box.

• path (use dialog) —

path specifies the absolute path to the file or directory you want to delete. If path is empty
(default), the function displays a dialog box from which you can select a file or directory. If you
specify an empty or relative path, this function returns an error. cancelled is TRUE if you cancel
the dialog box.

• entire hierarchy (F) —

entire hierarchy determines whether this function deletes all contents in the folder. The default
is FALSE. If entire hierarchy is TRUE, this function deletes all files and folders within the
specified path.

• confirm (F) —

If confirm is TRUE, the function displays a dialog box and asks you to confirm the delete
operation. The default is FALSE.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• deleted path —

deleted path is the path of the deleted file or folder.deleted path returns <Not A Path> if an
error occurred.

• cancelled —

cancelled is TRUE if you cancel the file dialog box. Otherwise, cancelled is FALSE, even if this

© National Instruments 1787

 Functions

function returns an error.

• error out —

error out contains error information. This output provides standard error out functionality.

If path specifies a directory that is not empty or if you do not have write permission for
the file or directory specified by path and its parent directory, this function does not
remove the directory and returns an error. Set entire hierarchy to TRUE to set the
function to delete non-empty directories. Use the Set Permissions function to set the
permissions for a file or directory.

Flush File Function

Writes all buffers of the file identified by refnum to disk and updates the directory
entry of the file associated with refnum.

The file remains open, and refnum remains valid. Data written to a file often resides in
a buffer until the buffer fills up or until you close the file. This function forces the
operating system to write any buffer data to the file.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file you want to flush.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum unchanged.

1788 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Deny Access Function

Reopens the instance of the file specified by refnum to temporarily change what read
or write access is denied to other refnums, VIs, or applications.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file you want to deny access to.

• deny mode (0:deny read/write) —

deny mode specifies what read or write access is denied.

0 deny read/write—Deny both read and write access to the file (default).
1 deny write-only—Permit read access but deny write access to the file.
2 deny none—Permit both read and write access to the file.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1789

 Functions

This function temporarily overrides permissions for a specific instance of the file. This
function does not modify permissions for the file itself. When you grant access to an
instance of a file, LabVIEW removes the override caused by denying access to the file so
that the file permissions and the deny mode associated with refnum determine
whether other refnums, VIs, or applications can read from or write to that instance of
the file. After the file refnum is closed, the permissions for that instance of the file are
no longer overridden.

Note You cannot deny access to a datalog file.

File/Directory Info Function

Returns information about the file or directory specified by path, including its size, its
last modification date, whether it is a directory, whether it is a shortcut, and the
resolved path if the file or directory is a shortcut. This function does not work for files
inside an LLB.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• path —

path specifies the absolute path to the file or directory whose attributes you want to determine.

If you wire an empty path to path, directory returns TRUE.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• directory —

1790 ni.com
 Functions

directory is TRUE if the path points to a directory and FALSE otherwise.

If you wire an empty path constant to path, directory returns TRUE.

• path out —

path out returns path unchanged.

• size —

size indicates the size of the file or directory specified by path.

If path specifies a directory, size indicates the number of items in the directory. (Windows) If
path is an empty path, size indicates the number of drives on the computer. (macOS and Linux)
If path is an empty path, size indicates the number of volumes on the computer. Otherwise, size
indicates the length in bytes of the specified file, whether the file is a datalog file or a byte
stream file.
• last mod —

last mod indicates the date and time at which the file or directory was last modified. The
number is a time zone-independent number of seconds that have elapsed since 12:00 a.m.,
Friday, January 1, 1904, Universal Time [01-01-1904 00:00:00].

• error out —

error out contains error information. This output provides standard error out functionality.

• resolved path —

resolved path returns the path to the shortcut target.

• shortcut —

shortcut is TRUE if the path points to a shortcut and FALSE otherwise.

Get Volume Info Function

Returns information about the volume containing the file or directory specified by
path, including the total storage space provided by the volume and the amount free in
bytes.

© National Instruments 1791

 Functions

Inputs/Outputs
• path —

path specifies the absolute path to the file or directory whose volume attributes you want to
determine.

If you specify an empty or relative path, this function returns an error.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• volume path —

volume path is a new path that specifies the volume on which the specified file or directory
resides.

• path out —

path out returns path unchanged.

• size (bytes) —

size (bytes) indicates the amount of storage, in bytes, provided by the specified volume.

• free (bytes) —

free (bytes) indicates the amount of storage, in bytes, available on the specified volume.

• error out —

error out contains error information. This output provides standard error out functionality.

• sector size (bytes) —

sector size (bytes) indicates the size, in bytes, of the smallest physical storage unit on disk. If you
open a file without buffering, you must make the size of the data in that file a multiple of the

1792 ni.com
 Functions

given sector size.

The volume where the file is located determines the sector size.

Create Folder Function

Creates the appropriate folder specified by path.

This function creates all folders that do not already exist in the specified path. If a file
or folder already exists at the specified location, the function returns an error instead
of overwriting the existing file or folder.

Inputs/Outputs
• prompt (Create Folder) —

prompt (Create Folder) is the message that appears above the list of files and directories, or
folder, in the file dialog box.

• path (use dialog) —

path is the absolute path to the folder you want to create.

If you do not wire data to path, the function displays a dialog box from which you can select a
folder. If you specify an empty or relative path, this function returns an error.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• created path —

created path specifies the new location of the folder.

© National Instruments 1793

 Functions

If the operation is unsuccessful, this function sets created path to <Not A Path>.

• cancelled —

cancelled is TRUE if you cancel the file dialog box. Otherwise, cancelled is FALSE, even if this
function returns an error.

• error out —

error out contains error information. This output provides standard error out functionality.

List Folder Function

Returns two arrays of strings listing the names of all files and folders found in path,
filtering both arrays based upon pattern and filtering the filenames array based upon
the specified datalog type.

Inputs/Outputs
• datalog type —

datalog type can be any data type and restricts the filenames returned to only datalog files
containing records of the specified data type. Datalog records contain a time stamp cluster and a
cluster of the front panel data.

• path —

path identifies the folder whose contents you want to determine. If this is not an existing folder,
this function sets filenames and folder names to empty arrays and returns an error. If path
points to a VI library (*.llb), filenames returns the contents of the VI library and folder names
returns an empty array.

• error in —

1794 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• pattern —

pattern restricts the files and directories returned to those whose names match pattern.

The pattern matching in this function is similar to the matching used in matching wildcards in
Windows and Linux filenames and is not like the regular expression matching performed by the
Match Pattern function and the Match Regular Expression function. If you specify characters
other than the question mark character (?) or the asterisk character (*), the function displays
only files or directories that contain those characters. You can use the question mark character
(?) to match any single character. You can use the asterisk character (*) to match any sequence of
zero or more characters.

If pattern is an empty string, the VI returns all files and directories.

• path out —

path out returns path unchanged.

• filenames —

filenames contains the names of the files found in the specified directory. This function does not
return the names of files found in folders within the directory. This function sorts the returned
filenames alphabetically.

• folder names —

folder names contains the names of the folders found in the specified directory. This function
sorts the folder names alphabetically. If path is an empty path, folder names contains the names
of the drives on the computer.

• error out —

error out contains error information. This output provides standard error out functionality.

Note Front panel controls might not update while the function lists files and
folders found in the specified directory. The controls update when the
function finishes listing the files and folders.

© National Instruments 1795

 Functions

Check if File or Folder Exists

Checks whether a file or folder exists on disk at a specified path. This VI works with
standard files and folders as well as files in LLB files.

Inputs/Outputs
• path —

path specifies the path to the file or folder you want LabVIEW to look for.

If you use this VI to check the validity of a network path, make sure that you connect to the
network first.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• dup path —

dup path returns path unchanged.

• file or folder exists? —

file or folder exists? is TRUE if the file or folder you specify in path exists on disk and FALSE if the
file or folder you specify in path does not exist on disk. If you wire an empty path to path, file or
folder exists? returns TRUE because the empty path refers to the list of drives mapped to the
computer. (macOS) The empty path refers to the mounted volumes. (Linux) The empty path
refers to the root directory.

• error out —

error out contains error information. This output provides standard error out functionality.

1796 ni.com
 Functions

Recursive File List

Lists the contents of a folder or LLB.

Inputs/Outputs
• Folder Path —

Folder Path specifies the path to the folder or LLB whose contents you want LabVIEW to return.

Note This VI does not support shortcuts and symbolic links to folders or LLB files.
Specify a path to the target folder or LLB instead of its shortcut or symbolic link.

• Treat LLBs as Folders? —

Treat LLBs as Folders? specifies whether to list LLBs as files or folders. If Treat LLBs as Folders?
is TRUE, this VI includes LLBs in the list of folders. If Treat LLBs as Folders? is FALSE, this VI
includes LLBs in the list of files. The default is FALSE.

If Folder Path specifies the path to an LLB, this VI ignores this input and returns all files,
including LLBs, in All Files in Dir.

• Continue Recursing on Error? (F) —

Continue Recursing on Error? specifies whether to continue recursing directories if an error

occurs. If Continue Recursing on Error? is TRUE, the VI continues recursing directory contents
after the error occurs. If Continue Recursing on Error? is FALSE, the VI stops recursing directory
content when the error occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• pattern —

© National Instruments 1797

 Functions

pattern specifies the pattern for files for which you want to search in Folder Path.

You can use the question mark character (?) to match any single character. You can use the
asterisk character (*) to match any sequence of zero or more characters. For example, if you
want this VI to find a list of the VIs in a folder, specify *.vi for pattern.

• Folders to Exclude —

Folders to Exclude specifies folder names you want to exclude during the recursion. Any folder
you exclude does not appear in the All Folders array. This input is case insensitive.

• All Folders —

All Folders returns a list of all subfolders, and shortcuts to folders in Folder Path.

• dup Folder Path —

dup Folder Path returns Folder Path unchanged.

• All Files in Dir —

All Files in Dir returns a list of all files in Folder Path. If Treat LLBs as Folders? is set to TRUE, the
list of files includes LLBs. The list also includes shortcuts to files.

• Number of Files —

Number of Files returns the number of files in the All Files in Dir array.

• error out —

error out contains error information. This output provides standard error out functionality.

Path To String Function

Converts path into a string describing a path in the standard format of the platform.

The connector pane displays the default data types for this polymorphic function.

1798 ni.com
 Functions

Inputs/Outputs
• path —

path is the path, array of paths, cluster of paths, or array of clusters of paths you want to convert
to a string.

If path is <Not A Path>, the function sets string to <Not A Path>.

• string —

string is the path descriptor(s) represented by path in the standard format for the current
platform. string is of the same data type structure as path.

String To Path Function

Converts a string, describing a path in the standard format for the current platform, to
a path.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• string —

string can be a string or any data structure that contains only strings, such as an array or clusters
of strings.

• path —

path is the platform-independent representation of the path described by string.

If string is not a valid path descriptor on the current platform, the function sets path to <Not a
Path>. path is of the same data type structure as string.

Note If string is <Not a Path>, the function returns a path to <Not a Path>. If
you attempt to use the path, LabVIEW cannot find the file and throws an error.

© National Instruments 1799

 Functions

Path to Array of Strings Function

Converts a path into an array of strings and indicates whether the path is relative.

Inputs/Outputs
• path —

path is the path you want to convert to an array of strings.

If path is <Not A Path>, the array of strings is empty and relative is FALSE.
• relative —

relative indicates whether the path you converted is a relative path or an absolute path.

If TRUE, it is a relative path. If FALSE, it is an absolute path.

• array of strings —

array of strings contains the components of the path.

The first element is the first step of the path hierarchy. For file systems that support multiple
volumes, the first element is the volume name. If path is a network path, the first element of
array of strings includes the name of the server in addition to the first step of the path hierarchy.
The last element of array of strings is the file or directory specified by the path.

Array of Strings to Path Function

Converts an array of strings into a relative or absolute path.

If you have an empty string in the array, the directory location before the empty string
is deleted in the path output. This behavior is similar to moving up a level in directory
hierarchy.

1800 ni.com
 Functions

Inputs/Outputs
• relative —

relative indicates whether you want to create a relative path or an absolute path.

If TRUE, the function creates a relative path. If FALSE (default), the function creates an absolute
path. If FALSE and the path specified is not valid as an absolute path (for example, the path
means go up a level), the function sets path to <Not A Path>.

• array of strings —

array of strings contains the names of the components of the path you want to build.

The first element is the highest level of the path hierarchy (the volume name, for file systems
that support multiple volumes), and the last element is the last element of the hierarchy. An
element that contains an empty string tells LabVIEW to go up a level in the hierarchy.

Note Each string in the array of strings must represent a single element of the
complete path. Partial paths, such as test\subtest, are not valid as array
elements because they might produce invalid paths on platforms that use different
directory separators.

• path —

path is the resulting path.

Suppose the path to the VI containing this function is c:\dir1\main.vi. To use this
function to build a relative path to another VI such as c:\dir1\dir2\called.vi,
wire TRUE to relative. In array of strings, enter dir2 as the first element and
called.vi as the second element. The function returns a relative path of dir2\
called.vi. You can use the Build Path function to append the relative path to the
output of the Current VI's Path function.

To build an absolute path to c:\dir1\dir2\called.vi, wire FALSE to relative. In

array of strings, enter c as the first element, dir1 as the second element, dir2 as
the third element, and called.vi as the fourth element. The function returns an
absolute path of c:\dir1\dir2\called.vi.

© National Instruments 1801

 Functions

Refnum to Path Function

Returns the path associated with the specified refnum.

Inputs/Outputs
• refnum —

refnum is the refnum of an open file whose associated path you want to determine.

If refnum is not a valid refnum, this function sets path to <Not A Path>, meaning refnum is
not associated with any open file. You can wire only file refnums to refnum. You cannot wire
configuration file refnums to refnum.
• path —

path is the corresponding path to refnum.

Path Type Function

Returns the type of the specified path, indicating whether it is an absolute, relative, or
<Not A Path>.

This function does not verify that the path exists on the computer. It checks only the
syntax of the path. Use the File/Directory Info function to verify that a file or directory
exists on the computer.

Inputs/Outputs
• path —

path specifies the path whose syntax you want to check.

• type —

1802 ni.com
 Functions

type indicates the type of the specified path.

UNC file paths are absolute file paths. Use two leading backslashes (\\) to represent UNC file
paths. type returns <Not A Path> only when you wire the Not A Path constant to this
function.

0 Absolute path
1 Relative path
2 <Not A Path>

Compare Two Paths

Compares Path 1 to Path 2 and returns a relative path between the two paths, the
common path between the two paths, and a Boolean that indicates whether the paths
are on the same path hierarchy level.

For example, if Path 1 is C:\folder\sub\test.txt and Path 2 is C:\folder\

sub2\dir\test2.doc, Relative Path from 1 to 2 returns ..\..\sub2\dir\
test2.doc. Common Path returns C:\folder, and Path 2 Relative to Path 1
returns FALSE because you have to go up two levels in the path hierarchy to get to the
common path between Path 1 and Path 2.

Inputs/Outputs
• Path 1 —

Path 1 specifies the first path.

• Path 2 —

Path 2 specifies the second path.

• error in (no error) —

© National Instruments 1803

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Relative Path from 1 to 2 —

Relative Path from 1 to 2 returns the relative path you have to take on disk to get from Path 1 to
Path 2.

• Common Path —

Common Path returns the part of the absolute path that Path 1 shares with Path 2.

• Path 2 Relative to Path 1? —

Path 2 Relative to Path 1? is TRUE if Path 1 is on the same directory level as Path 2. Otherwise,
this output is FALSE.

• error out —

error out contains error information. This output provides standard error out functionality.

Get File Extension

Returns the file extension, without the period (.), of a file you specify.

Inputs/Outputs
• file —

file specifies the path to the file whose extension you want LabVIEW to return.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

1804 ni.com
 Functions

• dup file —

dup file returns file unchanged.

• lowercase file extension —

lowercase file extension returns the extension of the file, without the period (.). LabVIEW always
returns a lowercase file extension, even if file contains uppercase letters.

• filename without extension —

filename without extension returns the name of the file you specify in file without the directory
path, period (.), or file extension. Unlike lowercase file extension, filename without extension
matches the case of the original filename.

• error out —

error out contains error information. This output provides standard error out functionality.

• unmodified file extension —

unmodified file extension returns the extension of the file you specify in file, without the period
(.). Unlike lowercase file extension, unmodified file extension matches the case of the original
file extension.

File Checksum

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

• SHA-256 File Checksum VI

• SHA-224 File Checksum VI
• SHA-512 File Checksum VI
• SHA-384 File Checksum VI
• SHA-512-256 File Checksum VI
• SHA-512-224 File Checksum VI
• SHA3-224 File Checksum VI

© National Instruments 1805

 Functions

• SHA3-256 File Checksum VI

• SHA3-384 File Checksum VI
• SHA3-512 File Checksum VI

SHA-256 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA-256 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA-224 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

1806 ni.com
 Functions

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA-224 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA-512 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides

© National Instruments 1807

 Functions

standard error in functionality.

• digest —

digest returns the SHA-512 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA-384 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA-384 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

1808 ni.com
 Functions

SHA-512-256 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA-512/256 message digest of the contents of the file as a hexadecimal
string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA-512-224 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

© National Instruments 1809

 Functions

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA-512/224 message digest of the contents of the file as a hexadecimal
string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA3-224 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

1810 ni.com
 Functions

digest returns the SHA3-224 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA3-256 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA3-256 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA3-384 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the

© National Instruments 1811

 Functions

polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA3-384 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

SHA3-512 File Checksum VI

Computes the message digest on the contents of a file. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• path —

path specifies the path to the file for which you want to compute the message digest.

• error in —

1812 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• digest —

digest returns the SHA3-512 message digest of the contents of the file as a hexadecimal string.

• error out —

error out contains error information. This output provides standard error out functionality.

Generate Temporary File Path

Returns a unique file path to the temporary directory. This VI only returns a path. It
does not create the temporary file.

Inputs/Outputs
• Temporary File Extension (tmp) —

Temporary File Extension (tmp) specifies the file extension.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Unique Temporary File Path —

Unique Temporary File Path returns a unique path to a non-existent file in the temporary
directory. You can use this path with other VIs when you want to create a file in the temporary
directory.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1813

 Functions

Datalog

Use the Datalog functions to open and close datalog files, read from and write to
datalog files, get and set datalog file positions, and get and set the number of datalog
records.

Palette
Description
Object
Open/Create/
Opens an existing datalog file, creates a new datalog file, or replaces an existing
Replace
datalog file, programmatically or interactively using a file dialog box. This function
Datalog
does not work for files inside an LLB.
Function
Close File Closes an open file specified by refnum and returns the path to the file associated
Function with the refnum.
Reads records from an open datalog file specified by refnum and returns it in
Read Datalog
record(s). Reading begins at the current datalog position. Use the Set Datalog
Function
Position function to move the current datalog position of the file.
Set Datalog
Moves the current datalog position of the file identified by refnum to the datalog
Position
position indicated by offset (in records) according to the mode in from.
Function
Set Number
of Records Sets the size in records of the datalog file identified by refnum.
Function
Write Datalog Writes record(s) to an open datalog file specified by refnum. Sets the current
Function datalog position to the end of the file before writing.
Get Datalog
Position Returns the current datalog position of the datalog file specified by refnum.
Function
Get Number
of Records Returns the size in records of the datalog file identified by refnum.
Function

1814 ni.com
 Functions

Open/Create/Replace Datalog Function

Opens an existing datalog file, creates a new datalog file, or replaces an existing
datalog file, programmatically or interactively using a file dialog box. This function
does not work for files inside an LLB.

You can optionally specify a dialog prompt or default filename. Use this function with
the intermediate Write Datalog or Read Datalog functions. Use the Close File function
to close the reference to the file.

Inputs/Outputs
• record type —

record type can be any data type. Wire a cluster matching the record data type and cluster order
to this input when creating datalog files.

• prompt —

prompt is the message that appears above the list of files and directories or folder in the file
dialog box.

• datalog path (use dialog) —

datalog path is the absolute path to the file.

If you do not wire datalog path, the function displays a dialog box from which you can select a
file. If you specify an empty or relative path, this function returns an error.

• operation (0:open) —

operation is the operation to perform. Error 43 occurs if you cancel the dialog box.

© National Instruments 1815

 Functions

0 open (default)—Opens an existing file. Error 7 occurs if the file cannot be found.
1 replace—Replaces an existing file by opening the file and setting its end of file to 0.
2 create—Creates a new file. Error 10 occurs if the file already exists.
3 open or create—Opens an existing file or creates a new file if one does not exist.
replace or create—Creates a new file or replaces a file if it exists. This VI replaces a file by
4
opening the file and setting its end of file to 0.
replace or create with confirmation—Creates a new file or replaces a file if it exists and you
5
give permission. This VI replaces a file by opening the file and setting its end of file to 0.

• access (0:read/write) —

access specifies how you plan to access the file.

read/write
0
(default)
1 read-only
2 write-only

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out is the reference number of the open file.

The value is Not A Refnum if the file cannot be opened.

• cancelled —

cancelled is TRUE if you cancel the file dialog box or if you do not select the replacement in an
advisory dialog box.

• error out —

error out contains error information. This output provides standard error out functionality.

1816 ni.com
 Functions

Close File Function

Closes an open file specified by refnum and returns the path to the file associated with
the refnum.

Error I/O operates uniquely in this function, which closes the file regardless of whether
an error occurred in a preceding operation. This ensures that files are closed correctly.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file you want to close.

• error in —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• path —

path is the corresponding path to refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\File IO\Datalog\Datalog File.lvproj

© National Instruments 1817

 Functions

Read Datalog Function

Reads records from an open datalog file specified by refnum and returns it in
record(s). Reading begins at the current datalog position. Use the Set Datalog Position
function to move the current datalog position of the file.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file you want to read. If you want to read more than
one element at a time, wire the count parameter.

• count (1) —

count is the number of datalog records to read.

The function returns count data elements in record(s), or if it reaches the end of the file, it
returns all the complete data elements read thus far and an end-of-file error. By default, the
function returns a single data element. If count is –1, the function reads the entire file. If count is
less than –1, the function returns an error.

If count calls for an array of elements and the record(s) data type is an array, the function
automatically returns a cluster of arrays or cluster array because LabVIEW does not allow arrays
of arrays.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• record(s) —

1818 ni.com
 Functions

record(s) contains the datalog records read from the file.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Datalog Position Function

Moves the current datalog position of the file identified by refnum to the datalog
position indicated by offset (in records) according to the mode in from.

The Write Datalog function changes the current datalog position to the end of the file.
You cannot use this function to write to a different position in the file.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the datalog file whose datalog position you want to
set.

• offset (in records) (0) —

offset (in records) specifies how many records from the location specified by from to set the
datalog position.

• from (0:start) —

from, together with offset (in records), specifies where to set the datalog position. If you wire
offset (in records), from defaults to 0, and the offset is relative to the beginning of the file. If you
do not wire offset (in records), offset (in records) defaults to 0, from defaults to 2, and the
operation starts at the current datalog position.

© National Instruments 1819

 Functions

start—Sets the datalog position offset (in records) from the beginning of the file. If from is 0,
0
offset (in records) should be positive.
end—Sets the datalog position offset (in records) from the end of the file. If from is 1, offset (in
1
records) should be negative.
2 current—Sets the datalog position offset (in records) from the current datalog position.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Number of Records Function

Sets the size in records of the datalog file identified by refnum.

LabVIEW reduces the number of records in a datalog file by deleting the last records in
the file until the records equal the number you enter. The number of records you enter
must be smaller than the number of records the datalog file holds. This function is not
a permanent limit, but an operation that affects the records already in the datalog file
one time. For example, if a datalog file contains 10 records and you set the number of
records to 5, then LabVIEW deletes the last 5 records. However, if you add 5 records,
the file then contains 10 records.

Inputs/Outputs
• refnum —

1820 ni.com
 Functions

refnum identifies the datalog file whose size you want to set.

• # of records —

# of records is the size in records of the datalog file you want to set.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

Write Datalog Function

Writes record(s) to an open datalog file specified by refnum. Sets the current datalog
position to the end of the file before writing.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the file to which you want to write.

• record(s) —

record(s) contains the datalog records to write to the datalog file.

record(s) must be either a data type that matches the record type specified when you open or
create the file or an array of such record types. In the former case, this function writes record(s)

© National Instruments 1821

 Functions

as a single record in the datalog file. If necessary, the function coerces numeric data to the
representation of the record type of this parameter. In the latter case, this function writes each
record in the array separately in the datalog file in row-major order.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Datalog Position Function

Returns the current datalog position of the datalog file specified by refnum.

Inputs/Outputs
• refnum —

refnum is the file refnum associated with the datalog file whose datalog position you want to
get.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• offset (in records) —

1822 ni.com
 Functions

offset (in records) returns the current datalog position in records.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Number of Records Function

Returns the size in records of the datalog file identified by refnum.

Inputs/Outputs
• refnum —

refnum identifies the datalog file whose size you want to get.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• refnum out —

refnum out returns refnum.

• # of records —

# of records is the number of records in the datalog file.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1823

 Functions

Packed Library

Use the Packed Library VIs to get and return data from a packed project library.

Palette Object Description

Get Exported File Returns the qualified names and paths of the exported files in a packed
List project library.

Get Exported File

Returns the path of an exported file in a packed project library.
Path

Returns the path to a packed project library for the VI you specify in vi
Packed Library Path
reference.

Get Exported File List

Returns the qualified names and paths of the exported files in a packed project library.

Inputs/Outputs
• packed library path —

packed library path specifies the path to the packed library.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• qualified names —

1824 ni.com
 Functions

qualified names returns an array of strings with the qualified names of the exported files in the
packed library.

• paths —

paths returns an array with the paths to the exported files in the packed library.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Exported File Path

Returns the path of an exported file in a packed project library.

Inputs/Outputs
• packed library path —

packed library path specifies the path to the packed library.

• qualified name —

qualified name specifies the qualified name of the exported file in the packed library.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path —

path returns the path to the exported file in the packed library.

• error out —

© National Instruments 1825

 Functions

error out contains error information. This output provides standard error out functionality.

Packed Library Path

Returns the path to a packed project library for the VI you specify in vi reference.

Inputs/Outputs
• vi reference —

vi reference specifies the reference to a VI in a packed library.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• vi reference out —

vi reference out returns vi reference unchanged.

• packed library path —

packed library path returns a path to the packed library that contains the VI you specify in vi
reference. If the referenced VI is not in a packed library, packed library path returns an empty
path.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Directory Recursive

Creates a directory and any parent directories it requires to exist.

1826 ni.com
 Functions

Inputs/Outputs
• directory —

directory specifies the path to the directory to create. If you specify a directory that already
exists, this VI does nothing.

• maximum path length —

maximum path length specifies the maximum number of characters allowed in the path. The
default is 252.

• permissions —

permissions specifies the permissions setting for the file or directory. The default is 111101101,
which is rwx r-x r-x in common file notation, and means the current user has permission to read,
write, and execute files in this directory; the current user's group members have permission only
to read and execute; all system users have permission only to read and execute.

Refer to Setting Permissions for more information about how to define the permissions you
want to set.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• directory copy —

directory copy returns directory unchanged.

• directories created —

directories created returns the path to the directory and paths to any parent directories this VI
creates.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1827

 Functions

Create File and Containing Folders

Creates a file at a specified path and any folders within that path that do not exist.

Inputs/Outputs
• file path —

file path specifies the path to the file you want to create. You must specify an absolute path. If
you specify an empty or relative path, this VI returns an error.

• access —

access specifies how to access the file.

The default is write-only.

0 read/write
1 read-only
2 write-only

• permissions —

permissions specifies the permissions setting for the file or directory. The default is 111101101,
which is rwx r-x r-x in common file notation, and means the current user has permission to read,
write, and execute files in this directory; the current user's group members have permission only
to read and execute; all system users have permission only to read and execute.

Refer to Setting Permissions for more information about how to define the permissions you
want to set.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• disable buffering (F) —

1828 ni.com
 Functions

disable buffering specifies if the file opens without buffering. The default is FALSE.

If you want to read or write a data file to a Redundant Array of Independent Disks (RAID),
consider opening the file without buffering to speed up data transfers. To disable buffering, wire
a TRUE value to the disable buffering input.

Note If you have a small amount of data to transfer, you might not notice a
difference if you disable buffering.

(macOS and Linux) LabVIEW ignores this input.

• refnum out —

refnum out returns the reference number of the file this VI creates.

• error out —

error out contains error information. This output provides standard error out functionality.

Contiguous and Noncontiguous Array Slices

To optimize performance, LabVIEW sometimes creates array slices from the arrays you
wire to certain Array functions. An array slice is an array created from another array,
and it contains some of the elements from the original array. LabVIEW expresses an
array slice as a (sub)array in the Context Help window when you move the cursor
over the wire for the resulting array. For example, (1-D (sub)array of) indicates that
the function creates an array slice, while (1-D array of) indicates the resulting array
contains all of the resulting elements.

Note The Context Help window only differentiates between arrays and
array slices if you allow debugging for the VI on the Execution page of the VI
Properties dialog box.

If LabVIEW creates an array slice, it may create a contiguous array slice, which stores
data adjacently, or a noncontiguous array slice, which stores data nonadjacently. If you
wire an array slice to the Preallocated Read from Binary File function, you might need
to know whether the array slice is contiguous or noncontiguous, because the function

© National Instruments 1829

 Functions

provides different levels of support that depend on the array you use.

Determining Whether LabVIEW Creates a Contiguous or Noncontiguous

Array Slice

Array functions in LabVIEW access data in row-major order. If you arrange the elements
of an array in row-major order, then LabVIEW represents that array in memory
contiguously. LabVIEW represents the following 2D array in memory contiguously as a
1D line from 0 to 15:

If you wire the previous array to the Index Array function and set the index (row) input
to 0, LabVIEW may return an array or a contiguous array slice. The array slice is
contiguous because LabVIEW represents the values in adjacent memory offsets 0, 1, 2,
3.

If you wire the previous array to the Index Array function and set the index (col) input
to 0, LabVIEW may return an array or a noncontiguous array slice. The array slice is
noncontiguous because LabVIEW represents the values in nonadjacent memory offsets
0, 4, 8, 12.

The following functions might return an array slice. If one of these functions returns an
array slice, use the following guidelines to determine whether LabVIEW creates a
contiguous or noncontiguous array slice:

• Array Subset—If LabVIEW represents the output from this function contiguously in
memory, it creates a contiguous array slice.
• Reverse 1D Array—If you wire an array to this function, it creates a noncontiguous
array slice. If you wire an already reversed array slice to this function, it creates a
contiguous array slice.
• Split 1D Array—If you wire an array to this function, it creates a contiguous array
slice. If you wire a noncontiguous array slice to this function, the resulting array
slice is either contiguous or noncontiguous based on how LabVIEW represents the
array slice in memory.
• Transpose 2D Array—This function creates a noncontiguous array slice unless you
wire an already transposed array to the function.
• Cluster to Array—This function creates a contiguous array slice.
• Index Array—This function creates a contiguous array slice unless you specify to
index the array column-wise.

1830 ni.com
 Functions

• Decimate 1D Array—This function creates a noncontiguous array slice.

Setting Permissions

The Set Permissions function includes a permissions input that allows you to control
access to files and directories that you create. To define the permissions you want to
set, you can wire the permissions output of the Get Permissions function to the
permissions input of the Set Permissions function, or you can wire a constant or a
control.

The following illustration shows the format of the permissions parameter.

The 9 bits that the permissions parameter uses are divided into three sets: user, group,
and others. Each set is divided into three permission categories: read, write, and
execute. Read determines if members of a set can read a file or directory. Write
determines if members of a set can write data to a file or directory. Execute determines
if members of a set can execute the file. A 1 in the bit grants permission.

For example, the following illustration shows how to grant a user permission to read
from, write to, and execute a file, and deny permission from the other two sets.

This structure is based on the Linux permission bits that govern read, write, and
execute permissions for users, groups, and others.

(Windows) Use of the permissions parameter is very limited on non-Linux operating

systems. You can use permissions to change only write permissions for users (bit 7);
the operating system ignores all other changes to the bits. Wire the binary value 0 to
permissions to deny user write permissions. The operating system grants read and
write permissions by default when you create any new file or directory but does not
allow you to change read permissions or set permissions for groups or others. Execute

© National Instruments 1831

 Functions

permissions do not apply to non-Linux operating systems. Therefore, wiring 0 to

permissions modifies only user write permissions for the new file or directory.
(Windows) The operating system also ignores permissions when creating new
directories. You can use permissions only when creating a new file.

(macOS) The read, write, and execute categories correspond to the See Files, Make
Changes, and See Folders access rights, respectively.

You can enter the value for permissions in any numeric format. For example, you can
change the numeric format to octal format to shorten the binary number with which
you set the file or directory permissions. Octal format shortens each three-bit group
within the parameter to a single octal value. (Windows) For example, to make a file
writable, enter the octal value 200, which corresponds to the binary representation
10000000. (Linux) To grant users read, write, and execute permissions, enter the
octal value 700, which corresponds to the binary value 111000000.

UNC Filename Support of File I/O VIs on Windows

UNC filenames provide the primary means for specifying the location of a file or
directory in a networked environment. In LabVIEW, you can enter and view UNC
filenames in path controls, indicators, and constants in a file dialog box. UNC
filenames use the following path form.

\\<machine>\<share name>\<dir>\...\<file or dir>

where <machine> is the name of the computer that you want to access on the
network, <share name> is the name of a shared drive on that machine, <dir>\...
consists of the name of the directory and subdirectories in which you want to store the
file, and <file> consists of the name that you want to call the file.

Timing
Use the Timing VIs and Functions to manipulate the speed at which an operation
executes and to retrieve time and date information from the computer clock.

1832 ni.com
 Functions

Palette
Description
Object
Tick Count
(ms) Returns the value of the millisecond timer.
Function

Returns the relative current time in seconds. Use the difference between two
High
successive values to measure the elapsed time between the calls. Use this VI to
Resolution
measure time spans with much higher resolution than you can obtain from the Tick
Relative
Count (ms) function. The time resolution of this VI may vary with different operating
Seconds
systems and CPU types.

Waits the specified number of milliseconds and returns the value of the millisecond
Wait (ms)
timer. (Windows) The actual wait time may be up to 1 ms shorter than the requested
Function
wait time.
Waits until the value of the millisecond timer becomes a multiple of the specified
Wait Until
millisecond multiple. Use this function to synchronize activities. You can call this
Next ms
function in a loop to control the loop execution rate. However, it is possible that the
Multiple
first loop period might be short. Wiring a value of 0 to the milliseconds multiple input
Function
forces the current thread to yield control of the CPU.

Stall Data
Delays the data flow of the wire for a specified period of time.
Flow

Get Date/ Converts a timestamp value or a numeric value to a date and time string in the time
Time zone configured for the computer. The function interprets timestamp and numeric
String values as the time-zone-independent number of seconds that have elapsed since 12:00
Function a.m., Friday, January 1, 1904, Universal Time.
Get Date/
Time In Returns a timestamp of the current time. LabVIEW calculates this timestamp using the
Seconds number of seconds elapsed since 12:00 a.m., Friday, January 1, 1904, Universal Time.
Function
Date/Time
To
Creates a timestamp from a set of individual values that specify a date and time.
Seconds
Function
Seconds Converts a timestamp value or a numeric value to a cluster of time values. This
To Date/ function loses fractional seconds of precision when converting the timestamp. If you
Time convert date time rec back into a time stamp, the timestamp may not display the

© National Instruments 1833

 Functions

Palette
Description
Object
Function exactly correct value.
To Time
Stamp Converts a number to a timestamp.
Function

Time
Inserts a time delay into the calling VI.
Delay

Elapsed
Indicates the amount of time that has elapsed since the specified start time.
Time

Waits the specified number of seconds with higher resolution than you can obtain with
the Wait (ms) function. For example, use this VI in applications that require waiting
with sub-millisecond resolution between steps. The resolution of the timer this VI uses
High
varies with different operating systems and CPU types.
Resolution
Polling
Unlike the Wait (ms) function, if the number of seconds you specify is 0, this VI does not
Wait
force the current thread to yield control of the CPU. Use this VI with caution if you are
concerned about high CPU loads: this VI may use polling to achieve high timing
resolution for all or a portion of the wait time.

Format
Date/Time Displays a timestamp value or a numeric value as time in the format you specify using
String time format codes.
Function
Time
Stamp Use the time stamp constant to pass a time and date value to the block diagram.
Constant

Tick Count (ms) Function

Returns the value of the millisecond timer.

The base reference time (millisecond zero) is undefined. That is, you cannot convert
millisecond timer value to a real-world time or date. Be careful when you use this
function in comparisons because the value of the millisecond timer wraps from

1834 ni.com
 Functions

(2^32)–1 to 0.

Inputs/Outputs
• millisecond timer value —

millisecond timer value returns the value of the millisecond timer.

High Resolution Relative Seconds

Returns the relative current time in seconds. Use the difference between two
successive values to measure the elapsed time between the calls. Use this VI to
measure time spans with much higher resolution than you can obtain from the Tick
Count (ms) function. The time resolution of this VI may vary with different operating
systems and CPU types.

Note The operating system clock this VI uses is not tied to any absolute time
reference and may drift over time when compared to absolute time sources.
Avoid using this VI across long periods of time.

Inputs/Outputs
• relative seconds —

relative seconds returns the value of the second timer in seconds.

Wait (ms) Function

Waits the specified number of milliseconds and returns the value of the millisecond

© National Instruments 1835

 Functions

timer. (Windows) The actual wait time may be up to 1 ms shorter than the requested
wait time.

This function makes asynchronous system calls, but the nodes on the block diagram
execute synchronously. Therefore, this function does not complete execution until the
specified time has elapsed.

Inputs/Outputs
• milliseconds to wait —

milliseconds to wait specifies the number of milliseconds to wait. This function does not wait
longer than 0x7ffffff or 2,147,483,647 ms or about 25 days. To wait for a longer period, execute
the function multiple times or use the High Resolution Polling Wait function. Wiring a value of 0
to this parameter forces the current thread to yield control of the CPU.

• millisecond timer value —

millisecond timer value returns the value of the millisecond timer after the wait.

When LabVIEW calls a VI for example, if millisecond timer value is 112 ms and
milliseconds to wait is 10 ms, the VI finishes when millisecond timer value is greater
than or equal to 122 ms.

Use the Wait For Front Panel Activity function to eliminate the need for continually
polling the front panel to determine if the value of a front panel object changes.

Timer resolution is system dependent and might be less accurate than one
millisecond, depending on your platform. Use the Wait Until Next ms Multiple function
or the High Resolution Polling Wait VI to improve resolution.

Note The Wait (ms) function behaves differently on Windows and the
LabVIEW Real-Time Module. (Windows) The Wait (ms) function waits at least
the value specified by the following formula: milliseconds to wait minus 1

1836 ni.com
 Functions

ms. For example, if milliseconds to wait is 3 ms, the Wait (ms) function waits
at least 2 ms. If milliseconds to wait is 1 ms, the Wait (ms) function may
return without waiting at all. (Real-Time Module) The Wait (ms) function
waits at least the value specified in the milliseconds to wait input.

Wait Until Next ms Multiple Function

Waits until the value of the millisecond timer becomes a multiple of the specified
millisecond multiple. Use this function to synchronize activities. You can call this
function in a loop to control the loop execution rate. However, it is possible that the
first loop period might be short. Wiring a value of 0 to the milliseconds multiple input
forces the current thread to yield control of the CPU.

This function makes asynchronous system calls, but the nodes themselves function
synchronously. Therefore, it does not complete execution until the specified time has
elapsed.

Inputs/Outputs
• millisecond multiple —

millisecond multiple is the input that specifies how many milliseconds lapse when the VI runs.
Wiring a value of 0 to this parameter forces the current thread to yield control of the CPU.

• millisecond timer value —

millisecond timer value returns the value of the millisecond timer after the wait.

When LabVIEW calls a VI for example, if millisecond multiple is 10 ms and millisecond

timer value is 112 ms, the VI waits 8 more milliseconds until the millisecond timer
value is 120 ms, a multiple of 10.

© National Instruments 1837

 Functions

Stall Data Flow

Delays the data flow of the wire for a specified period of time.

Inputs/Outputs
• milliseconds to wait —

milliseconds to wait specifies the number of milliseconds that this VI waits to continue the data
flow.

• value in —

value in specifies the input value before the delay occurs. This input accepts any data type.

• millisecond timer value —

millisecond timer value returns the LabVIEW system time when the delay finishes.

• value out —

value out returns the value in value in.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Malleable VIs\Basics\Malleable VIs

Basics.lvproj

Get Date/Time String Function

Converts a timestamp value or a numeric value to a date and time string in the time
zone configured for the computer. The function interprets timestamp and numeric
values as the time-zone-independent number of seconds that have elapsed since

1838 ni.com
 Functions

12:00 a.m., Friday, January 1, 1904, Universal Time.

Inputs/Outputs
• date format (0) —

date format selects the appearance of the date string.

Date formats vary with your system configuration. To use a different date format, use the Format
Date/Time String function.

0 short—1/21/94
1 long—Friday, January 21, 1994
2 abbreviated—Fri, Jan 21, 1994

• time stamp —

time stamp can be a timestamp or a numeric. If numeric, this number is the time-zone-
independent number of seconds that have elapsed since 12:00 a.m., Friday, January 1, 1904,
Universal Time [01-01-1904 00:00:00]. The default is the current date and time.

If year is before 1904, time stamp is negative.

• want seconds? (F) —

want seconds? controls the display of seconds in the time string.

• date string —

date string is the string returned by the function according to the specified date format.

• time string —

time string returns the string formatted according to the configured time zone for your
computer. want seconds? controls whether the string includes seconds.

© National Instruments 1839

 Functions

Get Date/Time In Seconds Function

Returns a timestamp of the current time. LabVIEW calculates this timestamp using the
number of seconds elapsed since 12:00 a.m., Friday, January 1, 1904, Universal Time.

Use the To Double Precision Float function to convert the timestamp value to a lower
precision, floating-point number.

Inputs/Outputs
• current time —

current time returns a timestamp of the LabVIEW system time. LabVIEW calculates this
timestamp using the number of seconds elapsed since 12:00 a.m., Friday, January 1, 1904,
Universal Time [01-01-1904 00:00:00].

Timer resolution is system dependent and might be less accurate than one
millisecond, depending on your platform. When you perform timing, use the Tick
Count (ms) function to improve resolution.

Date/Time To Seconds Function

Creates a timestamp from a set of individual values that specify a date and time.

Use the To Double Precision Float function to convert the timestamp value to a lower
precision, floating-point number. The number is measured as the number of seconds
that have elapsed since 12:00 a.m., Friday, January 1, 1904, Universal Time, assuming
DST is set to 1.

1840 ni.com
 Functions

Inputs/Outputs
• date time rec —

date time rec is the date and time to convert. If is UTC is TRUE, date time rec is in Universal
Time. If is UTC is FALSE, date time rec is in the configured time zone for the computer.

• fractional second —

fractional second must be greater than or equal to 0 and less than 1.

• second —

second can be from 0 to 59.

• minute —

minute can be from 0 to 59.

• hour —

hour can be from 0 to 23.

• day of month —

day of month can be from 1 to 31.

• month —

month can be from 1 to 12.

• year —

year can be from 1600 to 3000.

• day of week —

day of week can be from 1 to 7, which correspond to Sunday and Saturday, respectively.

Note This function ignores day of week when building the timestamp.

• day of year —

© National Instruments 1841

 Functions

day of year can be from 1 to 366.

Note This function ignores day of year when building the timestamp.

• DST —

DST indicates whether the time is standard (0) or daylight savings time (1). You also can set
DST to -1 to have the VI determine the correct time automatically each time you run the VI.
If is UTC is TRUE, the function ignores the DST setting and uses Universal Time.

• is UTC (F) —

is UTC specifies if date time rec is in Universal Time or in the configured time zone for the
computer. If TRUE, date time rec is in Universal Time. The default is FALSE.

• time stamp —

time stamp is the time that represents the date and time specified by the individual values in
date time rec.

If year and month are out of range, the results are unpredictable.

Seconds To Date/Time Function

Converts a timestamp value or a numeric value to a cluster of time values. This

function loses fractional seconds of precision when converting the timestamp. If you
convert date time rec back into a time stamp, the timestamp may not display the
exactly correct value.

Inputs/Outputs
• time stamp —

1842 ni.com
 Functions

time stamp can be a timestamp or a numeric. If numeric, this number is the time-zone-
independent number of seconds that have elapsed since 12:00 a.m., Friday, January 1, 1904,
Universal Time [01-01-1904 00:00:00]. The default is the current date and time.

If year is before 1904, time stamp is negative.

• to UTC (F) —

to UTC specifies if date time rec is in Universal Time or in the configured time zone for the
computer. If TRUE, date time rec is in Universal Time.

The default is FALSE.

• date time rec —

date time rec returns the date and time. If to UTC is TRUE, date time rec is in Universal Time. If
to UTC is FALSE, date time rec is in the configured time zone for the computer.

• fractional second —

fractional second is the fractions of a second since the start of the second. Values must be
greater than or equal to 0 and less than 1.

• second —

second is the number of complete seconds since the start of the minute. Values can be 0 to
59.

• minute —

minute is the number of complete minutes since the start of the hour. Values can be 0 to 59.

• hour —

hour is the number of complete hours since midnight. Values can be 0 to 23.

• day of month —

day of month can be 1 to 31.

• month —

month can be 1 to 12.

• year —

© National Instruments 1843

 Functions

year can be from 1600 to 3000.

• day of week —

day of week can be 1 to 7, which correspond to Sunday and Saturday, respectively.

• day of year —

day of year can be 1 to 366.

• DST —

is DST returns a value for standard (0) or daylight saving time (1). If to UTC is TRUE, is DST is
standard (0).

To Time Stamp Function

Converts a number to a timestamp.

Inputs/Outputs
• number —

number can be a scalar number, array or cluster of numbers, array of clusters of numbers, and
so on, that represents the amount of seconds from the epoch time of 12 a.m., January 1, 1904
[01-01-1904 00:00:00].

• time stamp —

time stamp is a time-zone-independent number of seconds that have elapsed since 12:00 a.m.,
Friday, January 1, 1904, Universal Time [01-01-1904 00:00:00].

1844 ni.com
 Functions

Time Delay

Inserts a time delay into the calling VI.

Dialog Box Options

Option Description

Time delay Specifies how many seconds to delay running the calling VI. The default is
(seconds) 1.000.

Inputs/Outputs
• Delay Time (s) —

Specifies how many seconds to wait. The value you wire to this input overrides the value you set
in the configuration dialog box.

• error in (no error) —

Describes error conditions that occur before this node runs.

• error out —

Contains error information. This output provides standard error out functionality.

Components

Specifies how many seconds to delay running the calling VI. The default is 1.000.

Tick Count

Returns the value of a free running counter in the units specified. The output and
internal counter are both of the configured width.

© National Instruments 1845

 Functions

If you do not have the FPGA, Real-Time, or DSP modules, you can use the Tick Count
(ms) function instead.

Dialog Box Options

Option Description

Unit of time the VI uses for the counter.

Note (Windows) The Windows operating system supports only millisecond

resolution. If you select a µSec or Tick resolution under Windows, the VI does
not provide exact timing and instead provides an approximation that averages
to the requested time over the course of the timing interval. Windows does not
Counter
support resolutions under one millisecond and rounds them up to one
Units
millisecond.

• Ticks—Sets the counter units to a single clock cycle, the length of which is
determined by the clock rate for which the VI is compiled.
• µSec—Sets the counter units to microseconds.
• mSec—Sets the counter units to milliseconds.

Size of
Specifies the maximum time a timer can track. To save space on the FPGA, use the
Internal
smallest Size of Internal Counter possible for the FPGA VI.
Counter

Inputs/Outputs
• Tick Count(Ticks) —

Returns the value of a free running counter at the time the VI wakes up. A free running counter
rolls over when the counter reaches the maximum of Size of Internal Counter specified in the
configuration dialog box.

1846 ni.com
 Functions

Components

Specifies the maximum time a timer can track. To save space on the FPGA, use the
smallest Size of Internal Counter possible for the FPGA VI.

Unit of time the VI uses for the counter.

Wait

Delays for a certain time interval before the output data dependence becomes valid.

(Real-Time Module) The Wait Express VI waits the specified count time and then
returns the value of a free running counter. When the Wait Express VI executes, it sleeps
and blocks the execution of other code running in the same thread.

Dialog Box Options

Option Description

Unit of time the VI uses for the counter.

Note (Windows) The Windows operating system supports only millisecond

resolution. If you select a µSec or Tick resolution under Windows, the VI does
not provide exact timing and instead provides an approximation that averages
to the requested time over the course of the timing interval. Windows does not
Counter
support resolutions under one millisecond and rounds them up to one
Units
millisecond.

• Ticks—Sets the counter units to a single clock cycle, the length of which is
determined by the clock rate for which the VI is compiled.
• µSec—Sets the counter units to microseconds.
• mSec—Sets the counter units to milliseconds.

© National Instruments 1847

 Functions

Option Description

Size of
Specifies the maximum time a timer can track. To save space on the FPGA, use the
Internal
smallest Size of Internal Counter possible for the FPGA VI.
Counter

Inputs/Outputs
• Count(Ticks) —

The time spent in the component.

• Tick Count(Ticks) —

Returns the value of a free running counter at the time the VI wakes up. A free running counter
rolls over when the counter reaches the maximum of Size of Internal Counter specified in the
configuration dialog box.

If you do not have the FPGA, Real-Time, or DSP modules, you can use the Wait (ms)
function instead.

Note (Real-Time Module, Windows) When the Wait Express VI runs inside a
timed structure or a VI set to time-critical priority, it blocks the execution of
all other code in the same timed structure or VI because timed structures and
time-critical VIs are single-threaded. In all other cases, the Wait Express VI
sleeps while other code in the calling VI runs in parallel on separate threads.

Components

Specifies the maximum time a timer can track. To save space on the FPGA, use the
smallest Size of Internal Counter possible for the FPGA VI.

Unit of time the VI uses for the counter.

Elapsed Time

Indicates the amount of time that has elapsed since the specified start time.

1848 ni.com
 Functions

Dialog Box Options

Option Description

Specifies how much time must elapse before the Time has Elapsed
Elapsed time (seconds)
Boolean is set to TRUE. The default is 1.000.

Automatically reset
Resets the elapsed time marker.
after time target

Inputs/Outputs
• Reset —

Controls the initialization of the internal state of the VI. The default is FALSE.

• Time Target (s) —

Specifies how much time must elapse before the Time has Elapsed Boolean is set to TRUE. The
default is 1.

• Auto Reset —

Resets the start time to the value in Present (s) when the Express VI reaches the Time Target (s).

• error in (no error) —

Describes error conditions that occur before this node runs.

• Set Start Time (s) —

© National Instruments 1849

 Functions

Uses the current time or a time offset from 12:00 a.m., Friday, January 1, 1904 [01-01-1904
00:00:00] as the start time instead of the time this VI first ran.

If the value is 0, the Express VI uses the current time as the start time. The Express VI uses any
other value as the number of seconds offset from 12:00 a.m., Friday, January 1, 1904 [01-01-1904
00:00:00]. For example if the value is 1, the Express VI measures the elapsed time since 12:00:01
a.m., Friday, January 1, 1904 [01-01-1904 00:00:01]. You can wire this input to the Present (s)
output of another Elapsed Time Express VI to get this value.

• Present (s) —

Displays the present time in seconds since 12:00 a.m., Friday, January 1, 1904, Universal Time
[01-01-1904 00:00:00].

• Start Time Text —

If Automatically reset after time target is FALSE, displays (in text format) the date and time the
VI first ran or the time you wire to the Set Start Time (s) input. Otherwise displays the date and
time of the last reset.

• Present Text —

Displays the present date and time in text format.

• Time has Elapsed —

Indicates if the Elapsed Time (s) is greater than the start time plus Time Target (s).

• Get Start Time (s) —

If Automatically reset after time target is FALSE, displays the date and time the VI first ran or the
time you wire to the Set Start Time (s) input. Otherwise displays the date and time of the last
reset.

• error out —

Contains error information. This output provides standard error out functionality.

• Elapsed Time (s) —

Displays the amount of time in seconds that has elapsed since the start time and the Present (s)
time.

• Elapsed Time Text —

1850 ni.com
 Functions

Displays the amount of time in seconds that has elapsed since the start time.

Components

Specifies how much time must elapse before the Time has Elapsed Boolean is set to
TRUE. The default is 1.000.

Resets the elapsed time marker.

High Resolution Polling Wait

Waits the specified number of seconds with higher resolution than you can obtain with
the Wait (ms) function. For example, use this VI in applications that require waiting
with sub-millisecond resolution between steps. The resolution of the timer this VI uses
varies with different operating systems and CPU types.

Unlike the Wait (ms) function, if the number of seconds you specify is 0, this VI does
not force the current thread to yield control of the CPU. Use this VI with caution if you
are concerned about high CPU loads: this VI may use polling to achieve high timing
resolution for all or a portion of the wait time.

Inputs/Outputs
• seconds to wait —

seconds to wait specifies the number of seconds to wait.

If seconds to wait is equal to or less than 0, the VI does not wait at all. If seconds to wait is 0, this
VI also does not force the current thread to yield control of the CPU.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

© National Instruments 1851

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Format Date/Time String Function

Displays a timestamp value or a numeric value as time in the format you specify using
time format codes.

Inputs/Outputs
• time format string (%c) —

time format string specifies the format of the output string.

Time format codes (beginning with %) not recognized by the function as a format code return the
character literally. The default code is %c, which corresponds to the date/time representation
appropriate for the configured time zone for the computer. If time format string is an empty
string, the function uses the default.
• time stamp —

time stamp can be a timestamp or a numeric. If numeric, this number is the time-zone-
independent number of seconds that have elapsed since 12:00 a.m., Friday, January 1, 1904,
Universal Time [01-01-1904 00:00:00]. The default is the current date and time.

If year is before 1904, time stamp is negative.

• UTC format —

UTC format specifies if the output string is in Universal Time or in the configured time zone for
the computer. If TRUE, date/time string is in Universal Time.

The default is FALSE.

• date/time string —

date/time string is the formatted date/time string.

1852 ni.com
 Functions

This function calculates date/time string by copying time format string and replacing
each of the time format codes with the corresponding values. For example, the time
format string %y%m%d displays timestamp in the format yymmdd. The time format
string %y%m%d displays the date January 30, 2014 as 140130.

The following list describes some of the caveats to consider when you use this
function:

• LabVIEW returns abbreviated weekday and month names as numeric values for
systems that do not support abbreviated names, such as Chinese and Korean.
• The %c, %u, %x, %X, %z, and %Z format codes depend on operating system locale
support. The output of these codes is platform dependent. Interpretation of the
Daylight Saving Time rule also can vary by platform.
• The %p format code only takes effect at locales that use the 12-hour time system.
• Time format codes have leading zeros as necessary to ensure a constant field
width. An optional # modifier before the format code letter removes the leading
zeros from the following format codes: %#d, %#H, %#I, %#j, %#m, %#M,
%#s, %#S, %#U, %#w, %#W, %#X, %#y, %#Y. The # modifier does not
modify the behavior of any other format codes.

Related Information

Time Format Codes

Time Stamp Constant

Use the time stamp constant to pass a time and date value to the block diagram.

The default value is zero seconds since 12:00 a.m., Friday, January 1, 1904, Universal
Time [01-01-1904 00:00:00]. To change the time and date, right-click the constant and
select Data Operations»Set Time and Date from the shortcut menu to display the Set
Time and Date dialog box. You also can right-click the constant and select Data
Operations»Set Time to Now from the shortcut menu to set the time and date value to
the current time and date.

Note If you convert a time stamp to a variant, the variant indicator displays
the current value of the time stamp that you wired to it.

© National Instruments 1853

 Functions

Dialog & User Interface

Use the Dialog & User Interface VIs and functions to create dialog boxes to prompt
users with instructions.

Palette
Description
Object
One
Button
Displays a dialog box that contains a message and a single button.
Dialog
Function
Two
Button
Displays a dialog box that contains a message and two buttons.
Dialog
Function
Three
Button Displays a dialog box that contains a message and three buttons.
Dialog

Simple
Indicates whether an error occurred. If an error occurred, this VI returns a description of
Error
the error and optionally displays a dialog box.
Handler

General
Indicates whether an error occurred. If an error occurred, this VI returns a description of
Error
the error and optionally displays a dialog box.
Handler

Resets the error status to no error, code to 0, and source to an empty string. Use this VI
Clear
when you want to ignore an error. By default, this VI ignores all errors. Wire an error code
Errors
value to specific error code to clear if you only want to ignore a specific error.

1854 ni.com
 Functions

Palette
Description
Object

Error Use the Error Ring to quickly select and pass NI or custom error codes throughout your
Ring VI.

Merge
Merges error I/O clusters from different VIs and functions.
Errors

Error Converts an error or warning code to an error cluster. This VI is useful when you receive a
Cluster return value from a shared library call or when you return user-defined error codes.
From
Error Passing error code 0 means that no error occurred and the VI does not modify the error
Code cluster.

Find
Tests the error status of one or more low-level functions or subVIs that produce a
First
numeric error code as output.
Error

Error Use the error cluster constant to pass an error cluster value to the block diagram. Set this
Cluster value by clicking inside the constant with the Operating tool and specifying values for
Constant the status, code, and source elements.

Multiple Use the Multiple Errors VIs to convert an error cluster into different formats or to
Errors manipulate the attributes of an error cluster.

Prompt
Displays a standard dialog box that prompts users to enter information, such as a user
User for
name and password.
Input

Display
Message Displays a standard dialog box that contains an alert or a message for users.
to User
Write to
System Writes a message to the nierrlog system log for storage and subsequent viewing.
Log
Wait For Pauses the execution of the calling VI block diagram in run mode until the function

© National Instruments 1855

 Functions

Palette
Description
Object
Front
Panel
detects front panel activity in the front panel you want to monitor.
Activity
Function
Generate
Front Programmatically generates front panel activity so any VI execution halted by the Wait
Panel on Front Panel Activity function continues executing. No actual changes occur on the
Activity front panel.
Function
Color
Box Use the color box constant to supply a constant color value to the block diagram.
Constant
Listbox
Symbol
Use the listbox symbol ring constant to assign symbols to items in a listbox control.
Ring
Constant

Events Use the Events functions to register events dynamically and to create user events.

Use the Menu functions to modify the menus in LabVIEW applications. Use the functions
Menu
located on the top row of the palette to handle menu selections.

Use the Cursor VIs to change the appearance of the cursor on the front panel of a VI. For
example, if the VI is acquiring or analyzing data and can accept no user input, you might
Cursor want to change the cursor to an hourglass or watch cursor. After the VI finishes acquiring
or analyzing data and can accept user input, you can change the cursor back to the
default cursor.

Help Use the Help VI and functions to link from VIs to HTML files or compiled help files.

1856 ni.com
 Functions

One Button Dialog Function

Displays a dialog box that contains a message and a single button.

Inputs/Outputs
• message —

message is the text to display in the dialog box. The dialog box expands when you add more
text. This function automatically wraps the text based on the size of the dialog box. The dialog
box can display as much text as your computer screen can display. If you want a scrollbar to
show when the size of the dialog box exceeds your desired size, use the Three Button Dialog VI.
With this VI, you can convert a three button dialog box to a one or two button dialog box by
wiring an empty string to a button text input to hide that button.

• button name ("OK") —

button name is the name displayed in the dialog box button. The default is OK.

• true —

true returns a value of TRUE when this dialog box closes, regardless of whether you close the
dialog by using the dialog box button or by using the close window button. You may use this
output to provide execution ordering control for downstream functions.

Two Button Dialog Function

Displays a dialog box that contains a message and two buttons.

Inputs/Outputs
• message —

© National Instruments 1857

 Functions

message is the text to display in the dialog box. The dialog box expands when you add more
text. This function automatically wraps the text based on the size of the dialog box. The dialog
box can display as much text as your computer screen can display. If you want a scrollbar to
show when the size of the dialog box exceeds your desired size, use the Three Button Dialog VI.
With this VI, you can convert a three button dialog box to a one or two button dialog box by
wiring an empty string to a button text input to hide that button.

• T button name ("OK") —

T button name is the name displayed on one of the dialog box buttons. The default is OK.

• F button name ("Cancel") —

F button name is the name displayed on one of the dialog box buttons. The default is Cancel.

• T button? —

T button? returns a value of TRUE if you click the dialog box button named T button name. If
you click the dialog box button named F button name or click the close window button, T
button? returns a value of FALSE.

Three Button Dialog

Displays a dialog box that contains a message and three buttons.

Inputs/Outputs
• Justify Message (Left) —

Justify Message sets the justification of the text that is displayed.

1858 ni.com
 Functions

0 Left—Justifies the text to the left.

1 Center—Centers the text.
2 Right—Justifies the text to the right.

• Window Title ("") —

Window Title is the text to display in the title bar of the dialog box.

• message —

message is the text to display in the dialog box. The dialog box has a maximum size based on
your computer screen resolution and system font size. If the text exceeds the maximum size of
the dialog box, a vertical scrollbar appears on the right side. Scroll to display the text beyond the
maximum size.

• Left Button Text ("Yes") —

Left Button Text is the text to display on the left button. The default is Yes.

• Center Button Text ("No") —

Center Button Text is the text to display on the center button. The default is No.

• Right Button Text ("Cancel") —

Right Button Text is the text to display on the right button. The default is Cancel.

• Keyboard Shortcuts (Left is <Enter>) —

Keyboard Shortcuts specifies keyboard shortcuts for each button in the dialog box.

For example, you can specify a shortcut of <F1> for a Help button in the dialog box. The default is
a shortcut of <Enter> for the left button and no shortcuts for the center and right buttons.

• Left Button Key Shortcut —

Left Button Key Shortcut specifies a keyboard shortcut for the left button.

• Control —

© National Instruments 1859

 Functions

If Control is TRUE, the keyboard shortcut includes the <Ctrl> key.

• Shift —

If Shift is TRUE, the keyboard shortcut includes the <Shift> key.

• Key —

Key is the name of the shortcut key.

Key must match a key name on the Key Navigation page of the Properties dialog box.

• Center Button Key Shortcut —

Center Button Key Shortcut specifies a keyboard shortcut for the center button.

• Control —

If Control is TRUE, the keyboard shortcut includes the <Ctrl> key.

• Shift —

If Shift is TRUE, the keyboard shortcut includes the <Shift> key.

• Key —

Key is the name of the shortcut key.

Key must match a key name on the Key Navigation page of the Properties dialog box.

• Right Button Key Shortcut —

Right Button Key Shortcut specifies a keyboard shortcut for the right button.

• Control —

If Control is TRUE, the keyboard shortcut includes the <Ctrl> key.

1860 ni.com
 Functions

• Shift —

If Shift is TRUE, the keyboard shortcut includes the <Shift> key.

• Key —

Key is the name of the shortcut key.

Key must match a key name on the Key Navigation page of the Properties dialog box.

• Allow user to close window? (TRUE) —

If Allow user to close window? is TRUE (default), the operating system window close button
appears in the dialog box, and the user can close the dialog box without clicking the left, center,
or right buttons.

In most operating systems, the window close button appears in the upper right corner of the
window.

• Which Button? —

Which Button? indicates which button the user clicked.

0 Left Button
1 Center Button
2 Right Button
Window Close—The user closed the dialog box without clicking the left, center, or right
3
buttons.

If you wire an empty string to a button text input, this VI hides that button. This allows
you to convert a three button dialog box to a one or two button dialog box. For
example, you could use this functionality to hide a Help button when no help is
available. If you wire an empty string to all three button text inputs, this VI displays a
dialog box with a single default OK button.

© National Instruments 1861

 Functions

Simple Error Handler

Indicates whether an error occurred. If an error occurred, this VI returns a description

of the error and optionally displays a dialog box.

This VI calls the General Error Handler VI and has the same basic functionality as
General Error Handler but with fewer options.

Inputs/Outputs
• error code (no error:0) —

error code is a numeric error code.

If error in indicates an error, the VI ignores error code. If not, the VI tests it. A nonzero value
signifies an error.

• error source (" ") —

error source is an optional string you can use to describe the source of error code.

• type of dialog (OK msg:1) —

type of dialog determines what type of dialog box to display, if any.

Regardless of its value, the VI outputs the error information and message describing the error.

no dialog—Displays no dialog box. This is useful if you want to have programmatic control over
0
handling errors.
OK message (default)—Displays a dialog box with a single Continue button. After the user
1
acknowledges the dialog box, the VI returns control to the main VI.
continue or stop message—Displays a dialog box with buttons, which the user can use to
2
either continue or stop. If the user selects Stop, the VI calls the Stop function to halt execution.
OK message + warnings—Displays a dialog box with any warnings and a single Continue
3
button. After the user acknowledges the dialog box, the VI returns control to the main VI.

1862 ni.com
 Functions

continue/stop + warnings—Displays a dialog box with any warnings and buttons, which the
4 user can use to either continue or stop. If the user selects Stop, the VI calls the Stop function to
halt execution.

• error in (no error) —

error in describes error conditions that occur before this node runs.

This input contains status, code, and source, which provide standard error in cluster element
functionality.

• error? —

error? returns TRUE if an error occurs. If this VI finds an error, it sets the parameters in the error
cluster.

• code out —

code out is the error code indicated by error in or error code.

• source out —

source out indicates the source of the error.

The source out string is a more descriptive string than the source string in the error in input.

• error out —

error out contains error information. This output provides standard error out functionality.

• message —

message describes the error code that occurred, the source of the error, and a description of the
error.

If the VI does not return a description of the error, you can take several actions to find the error
code description. If more than one description exists for the same error code, the VI displays all
the descriptions, separated by or.

General Error Handler

Indicates whether an error occurred. If an error occurred, this VI returns a description

© National Instruments 1863

 Functions

of the error and optionally displays a dialog box.

Inputs/Outputs
• [user-defined descriptions] —

[user-defined descriptions] is an array of descriptions of user-defined codes.

If an incoming error matches one in user-defined codes, the VI returns the corresponding
description from user-defined descriptions in message.

• [user-defined codes] —

[user-defined codes] is an array of numeric error codes you can use to define error codes and
messages for your own VIs.

The VI searches this array after searching an internal database of error codes. Error codes -8999
through -8000, 5000 through 9999, and 500,000 through 599,999 are reserved for you to define
your own error messages.

• [error code] (0) —

[error code] is a numeric error code.

If error in indicates an error, the VI ignores error code. If not, the VI tests it. A nonzero value
signifies an error.

• [error source] (" ") —

[error source] is an optional string you can use to describe the source of error code.

• search ni.com link visible?(T) —

1864 ni.com
 Functions

search ni.com link visible? determines whether the Search ni.com for error hyperlink
appears in the dialog box. Set to TRUE to display the hyperlink. Clicking the hyperlink opens
search results for the error code on ni.com in the default web browser. The hyperlink appears
only for LabVIEW-defined error codes in the development environment. The default is TRUE.

• type of dialog (OK msg:1) —

type of dialog determines what type of dialog box to display, if any.

Regardless of its value, the VI outputs the error information and message describing the error.

no dialog—Displays no dialog box. This is useful if you want to have programmatic control over
0
handling errors.
OK message (default)—Displays a dialog box with a single Continue button. After the user
1
acknowledges the dialog box, the VI returns control to the main VI.
continue or stop message—Displays a dialog box with buttons, which the user can use to
2
either continue or stop. If the user selects Stop, the VI calls the Stop function to halt execution.
OK message + warnings—Displays a dialog box with any warnings and a single Continue
3
button. After the user acknowledges the dialog box, the VI returns control to the main VI.
continue/stop + warnings—Displays a dialog box with any warnings and buttons, which the
4 user can use to either continue or stop. If the user selects Stop, the VI calls the Stop function to
halt execution.

• error in (no error) —

error in describes error conditions that occur before this node runs.

This input contains status, code, and source, which provide standard error in cluster element
functionality.

• [exception action] (none:0) —

[exception action] is a way for you to create exceptions to error handling.

The VI performs the exception action if the error code and error source match the exception
code and exception source. If you use the default value for an exception source, only the
exception code must match for the VI to perform the exception action.

No exception (default)—Performs no error exception handling, even if you wire an exception

0
code or an exception source.
1 Cancel error on match—Treats what is normally an error as no error. If the VI cancels an error,

© National Instruments 1865

 Functions

error? is FALSE, code out is 0, and source out is an empty string.

Set error on match—Upgrades a warning to an error. This parameter sets an error if the VI
detects no error, as described in the status and error code parameters, but the code value of
2 error in matches exception code and the error source value matches exception source. If the VI
sets an error, error? is TRUE, code out is the code value from error in, and source out is the
source value from error in.

• [exception code] —

[exception code] is the error code that you want to treat as an exception. The default is 0.

• [exception source] —

[exception source] is the error message that you want to use to test for an exception. The default
is an empty string.

• error? —

error? returns TRUE if an error occurs. If this VI finds an error, it sets the parameters in the error
cluster.

• code out —

code out is the error code indicated by error in or error code.

• source out —

source out indicates the source of the error.

The source out string is a more descriptive string than the source string in the error in input.

• message —

message describes the error code that occurred, the source of the error, and a description of the
error.

If the VI does not return a description of the error, you can take several actions to find the error
code description. If more than one description exists for the same error code, the VI displays all
the descriptions, separated by or.

• error out —

error out contains error information. This output provides standard error out functionality.

1866 ni.com
 Functions

Clear Errors

Resets the error status to no error, code to 0, and source to an empty string. Use this VI
when you want to ignore an error. By default, this VI ignores all errors. Wire an error
code value to specific error code to clear if you only want to ignore a specific error.

Inputs/Outputs
• specific error code to clear (0: all) —

specific error code to clear ignores only the specific error code wired to this input. The default
value is 0, which means the VI will ignore all errors.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

The default is no error. If you do not wire a value to specific error code to clear, this node
does not pass the error in input to the error out output.

• specific error cleared? —

specific error cleared? indicates whether the error referenced by specific error code to clear has
been cleared.

• error out —

error out contains error information. This output provides standard error out functionality. error
out returns no error by default. If you wire a value to specific error code to clear and error in
contains errors that do not match the error code you wired, error out will return an error.

Error Ring

Use the Error Ring to quickly select and pass NI or custom error codes throughout your
VI.

© National Instruments 1867

 Functions

You can configure the ring to return a built-in error message or you can create a
custom error message for a one-time use. By default, the source string of the error
cluster contains the call chain from the top-level VI to the current VI.

Note To reduce unnecessary execution time in your VIs, place Error Rings
inside a case structure that executes only when the error condition the Error
Ring reports is met.

(Real-Time Module) Exclude the call chain to reduce jitter in real-time applications. You
cannot use the Error Ring in VIs that run on RT targets.

Inputs/Outputs
• error out —

The following is a configured Error Ring.

The configured Error Ring has the following parts.

Section Description
Toggles between error and warning.
Indicates if the error includes the call chain.
Description of the error. Right-click the Error Ring and select Visible Items»Error
Explanation Text from the shortcut menu to show or hide the error description.

6:LabVIEW Note You can include format specifiers, such as %s and %T, in the
description. Refer to Defining a Custom Error Code from the Error Ring for
more details.

1868 ni.com
 Functions

Section Description
Launches the Select Error dialog box.

After you select the error, you can change the type (Error or Warning) and whether to
include the call chain by clicking the icons on the ring. You also can toggle the error
type and call chain options by right-clicking the Error Ring and selecting Generate
Error, Generate Warning, Include Call Chain, or Exclude Call Chain from the shortcut
menu.

Merge Errors

Merges error I/O clusters from different VIs and functions.

By default, this function looks for errors beginning with the error in 0 parameter and
reports the first error found. If the function finds no errors, it looks for warnings and
returns the first warning found. If the function finds no warnings, it returns no error.
Use exception control to treat what is normally an error as no error or to treat a
warning as an error.

To configure the function to return an error cluster that combines all the specified
errors/warnings, right-click the function and select Retain All Errors.

Inputs/Outputs
• error in —

error in 0 describes the first error condition to check for errors.

• error in —

error in 1 describes the second error condition to check for errors.

• error out —

© National Instruments 1869

 Functions

error out returns the first error/warning in the specified inputs or an error cluster that combines
all the specified errors/warnings.

When you place this function on the block diagram, it has two inputs available. You
can add additional inputs to the node by right-clicking an input and selecting Add
Input from the shortcut menu or by resizing the node. To remove inputs, right-click an
input and select Remove Input from the shortcut menu or use resizing handles to
resize the node.

Error Cluster From Error Code

Converts an error or warning code to an error cluster. This VI is useful when you receive
a return value from a shared library call or when you return user-defined error codes.

Passing error code 0 means that no error occurred and the VI does not modify the
error cluster.

Inputs/Outputs
• is warning? (False) —

If is warning? is TRUE, status returns FALSE to indicate that a warning occurred. The default is
FALSE.

• show call chain? (False) —

If show call chain? is TRUE, source includes the chain of callers from the VI that produced the
error or warning to the top-level VI. The default is FALSE, which indicates to include only the
calling VI.

This VI uses the Call Chain function to obtain the chain of callers.

• error code (0) —

1870 ni.com
 Functions

error code is the code you want to convert to an error cluster. The default is 0, which indicates
that no error occurred.

• error message ("") —

error message is the error description to appear in the error out cluster.

LabVIEW displays the description in error message when the General Error Handler VI receives
this error out cluster. If error message is empty, LabVIEW uses error code to determine the error
description from existing LabVIEW error codes.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. With the following exception, this output provides
standard error out functionality.

If the value of error in is no error, this VI contains error information that corresponds to the
error code input.

Find First Error

Tests the error status of one or more low-level functions or subVIs that produce a
numeric error code as output.

Inputs/Outputs
• error codes —

error codes is an array of the numeric error codes assembled from local subVIs or functions. If
there is no error indicated in the error in cluster, the VI tests these codes in ascending order for
nonzero values. If the VI finds a nonzero value, error out reflects the error status of that input.

© National Instruments 1871

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• source messages —

source messages contains the source message you want to appear in the error out cluster if the
VI finds an error in error codes. Place each message on a separate line in a string constant or
control. Use of this input is optional.

• error? —

error? is TRUE if the error in cluster or any of the error codes reflects an error.

• error out —

error out contains error information. This output provides standard error out functionality.

If this VI finds an error, it sets the parameters in the error out cluster. You can wire this
cluster to the Simple Error Handler or General Error Handler to identify the error and
describe it to the user.

Error Cluster Constant

Use the error cluster constant to pass an error cluster value to the block diagram. Set
this value by clicking inside the constant with the Operating tool and specifying values
for the status, code, and source elements.

Multiple Errors

Use the Multiple Errors VIs to convert an error cluster into different formats or to
manipulate the attributes of an error cluster.

1872 ni.com
 Functions

Palette Object Description

Error Cluster to Converts a cluster of errors into an array of encoded errors. This VI returns an
Array of Errors empty array if the error cluster does not include any errors.

Convert to
Legacy Error Converts an error cluster from JSON encoded format to legacy format.
Cluster
Convert to
Encoded Error Converts an error cluster from legacy format to JSON encoded format.
Cluster

Updates the value of an attribute stored in an error cluster. If the specified

Write Error attribute name is not found, this VI adds the attribute with the specified value to
Cluster the error cluster.
Attribute
For a single cluster that stores multiple errors, this VI updates only the first error.

Remove Error
Cluster Removes an attribute from an error cluster.
Attribute

List Error
Returns the names of all attributes stored in an error cluster. For a single cluster
Cluster
that stores multiple errors, this VI lists only the attribute names of the first error.
Attributes

Read Error
Returns the value of an attribute stored in an error cluster. If the attribute is not
Cluster
found, this VI returns an empty string.
Attribute

Error Cluster to Array of Errors

Converts a cluster of errors into an array of encoded errors. This VI returns an empty
array if the error cluster does not include any errors.

To create a cluster of errors from multiple VIs or functions, use the Merge Errors
function.

© National Instruments 1873

 Functions

Inputs/Outputs
• error —

error specifies an error cluster that you use to check for errors or warnings.

• array of errors —

array of errors returns an array of all the error clusters, encoded in either JSON or legacy format.

Convert to Legacy Error Cluster

Converts an error cluster from JSON encoded format to legacy format.

Inputs/Outputs
• error in —

error in specifies an error cluster that you use to check for errors or warnings.

• error out —

error out returns the error from error in, encoded in legacy format.

Convert to Encoded Error Cluster

Converts an error cluster from legacy format to JSON encoded format.

1874 ni.com
 Functions

Inputs/Outputs
• error in —

error in specifies an error cluster that you use to check for errors or warnings.

• error out —

error out returns the error from error in, encoded in JSON format.

Write Error Cluster Attribute

Updates the value of an attribute stored in an error cluster. If the specified attribute
name is not found, this VI adds the attribute with the specified value to the error
cluster.

For a single cluster that stores multiple errors, this VI updates only the first error.

Inputs/Outputs
• error in —

error in specifies an error cluster that you use to check for errors or warnings.

• attribute name —

attribute name specifies the name of the attribute that you want to update.

• JSON value —

JSON value specifies the value, in JSON format, to set for the attribute.

• error out —

error out returns an error cluster with the value of the specified attribute updated or with the
specified attribute added.

• created? —

© National Instruments 1875

 Functions

created? returns TRUE if the VI added the specified attribute and value to the error cluster. This
output returns FALSE if the VI found the specified attribute name in the error cluster and
updated the value.

Remove Error Cluster Attribute

Removes an attribute from an error cluster.

Inputs/Outputs
• error in —

error in specifies an error cluster that you use to check for errors or warnings.

• attribute name —

attribute name specifies the name of the attribute that you want to remove.

• error out —

error out returns an error cluster with the attribute removed. If the attribute is not found, this
output returns the same error as error in.

• deleted? —

deleted? indicates if the attribute is removed.

List Error Cluster Attributes

Returns the names of all attributes stored in an error cluster. For a single cluster that
stores multiple errors, this VI lists only the attribute names of the first error.

1876 ni.com
 Functions

Inputs/Outputs
• error —

error specifies an error cluster that you use to check for errors or warnings.

• attribute names —

attribute names returns the names of all attributes stored in the error cluster.

Read Error Cluster Attribute

Returns the value of an attribute stored in an error cluster. If the attribute is not found,
this VI returns an empty string.

Inputs/Outputs
• error —

error specifies an error cluster that you use to check for errors or warnings.

• attribute name —

attribute name specifies the name of the attribute that you want to read.

• JSON object string —

JSON object string returns the JSON objects stored in the error cluster.

• value string —

value string returns the value of the attribute.

• found? —

found? indicates if the attribute is found.

© National Instruments 1877

 Functions

Prompt User for Input

Displays a standard dialog box that prompts users to enter information, such as a user
name and password.

Dialog Box Options

Option Description
Message
to Contains the text to display in the dialog box.
Display
Contains the following options:

• First button name—

Specifies the text that appears on the first button. By default, the text on the first
button is OK.

Buttons • Second button name—

to
Display Specifies the text that appears on the second button. By default, the text on the
second button is Cancel. This option is available only when you place a checkmark
in the Display second button checkbox.

• Display second button—

Specifies whether a second button is displayed in the dialog box.

Specifies the name and data type of the controls that appear in the dialog box. The
Inputs you list here are returned as outputs on the block diagram.
Inputs
Input Name is the name of the control and instructs users what to enter into the control.
Input Data Type is the type of control you want to use in the dialog box. You can choose
from the following options: Number, Checkbox, or Text Entry Box.

1878 ni.com
 Functions

Option Description
Contains the following options:

• Delete—

Edit Deletes the selected input.

Inputs
• Insert—

Inserts a new row in the Inputs list above the selected row.

Window
Contains the text to display in the title bar of the dialog box.
Title

Inputs/Outputs
• error in (no error) —

Describes error conditions that occur before this node runs.

• Enable —

Enables or disables the Express VI. The default is ON or TRUE.

• OK —

Returns TRUE when you click the first button in the dialog box and FALSE when you click the
second button.

• error out —

Contains error information. This output provides standard error out functionality.

Note The behavior of this VI changes depending upon the target. If the
current target does not or might not have a host computer connected, the
configuration dialog box displays warnings next to options that are invalid
without a host. If you configure this VI to prompt for input and run the VI on a
target with no user interface, such as the Real-Time Module with no host
computer connected, this VI returns an error.

© National Instruments 1879

 Functions

Components

Inserts a new row in the Inputs list above the selected row.

Deletes the selected input.

Specifies whether a second button is displayed in the dialog box.

Contains the text to display in the title bar of the dialog box.

Specifies the text that appears on the second button. By default, the text on the second
button is Cancel. This option is available only when you place a checkmark in the
Display second button checkbox.

Specifies the text that appears on the first button. By default, the text on the first
button is OK.

Contains the text to display in the dialog box.

Specifies the name and data type of the controls that appear in the dialog box. The
Inputs you list here are returned as outputs on the block diagram.

Display Message to User

Displays a standard dialog box that contains an alert or a message for users.

Dialog Box Options

Option Description
Message
to Contains the text to display in the dialog box.
Display
Buttons Contains the following options:

1880 ni.com
 Functions

Option Description

• First button name—

Specifies the text that appears on the first button. By default, the text on the first
button is OK.

• Second button name—

to
Display Specifies the text that appears on the second button. By default, the text on the
second button is Cancel. This option is available only when you place a checkmark
in the Display second button checkbox.

• Display second button—

Specifies whether a second button is displayed in the dialog box.

Inputs/Outputs
• error in (no error) —

Describes error conditions that occur before this node runs.

• Enable —

Enables or disables the Express VI. The default is ON or TRUE.

• Message —

Contains the text to display in the dialog box.

• OK? —

Returns TRUE when you click the first button in the dialog box and FALSE when you click the
second button.

• error out —

Contains error information. This output provides standard error out functionality.

© National Instruments 1881

 Functions

Components

Specifies whether a second button is displayed in the dialog box.

Specifies the text that appears on the first button. By default, the text on the first
button is OK.

Contains the text to display in the dialog box.

Specifies the text that appears on the second button. By default, the text on the second
button is Cancel. This option is available only when you place a checkmark in the
Display second button checkbox.

Write to System Log

Writes a message to the nierrlog system log for storage and subsequent viewing.

Inputs/Outputs
• message —

message is the text to write to the system log.

• severity (Error) —

severity specifies how the system log classifies the message.

0 Error—Specifies the message as an error.

1 Warning—Specifies the message as a warning.
2 Informational—Specifies the message as informational text.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

1882 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

You can view the messages this VI writes using the system log viewer for your
operating system.

(Windows) Open the Application page of the Windows Event Viewer.

(macOS) Use Console to view the system log.

(Linux) Use a system log viewer appropriate to your distribution.

(NI Linux Real-Time) Open the System Log Viewer page of NI Web-based Configuration
& Monitoring.

(Phar Lap ETS, VxWorks) Open the console. The messages display alongside other
console output.

Wait For Front Panel Activity Function

Pauses the execution of the calling VI block diagram in run mode until the function
detects front panel activity in the front panel you want to monitor.

Inputs/Outputs
• do not wait! (False) —

If do not wait! is TRUE, the VI runs without pausing execution.

• front panel (this VI's panel) —

front panel is a reference to the VI you want to monitor for front panel activity.

You can wire a VI, front panel, or control reference to this input. If you wire a control reference,

© National Instruments 1883

 Functions

the function monitors the activity of the front panel containing the control. If you do not specify
a reference, the function monitors the front panel activity of the VI in which you place the
function.

You must wire a reference to a VI or object in a local application instance. You cannot wire a
reference to a VI or object in a remote application instance.

• timeout ms (-1 never timeout) —

timeout ms specifies the time, in milliseconds, that the function waits before it lets the VI
continue execution. The default value is –1, which indicates to wait indefinitely.

• millisecond timer value —

millisecond timer value returns the value of the millisecond timer.

This function is similar to the Occurrences functions. Use this function if you want a
block diagram to execute only after a user changes the value of a front panel object,
such as when the user clicks a button, turns a knob, or enters data. This function
activates that block diagram if the function detects user activity on the front panel. Use
this function to eliminate the need for continually polling the front panel to determine
if the value of a front panel object changes. You also can use this function to monitor
activity on a remote front panel.

Note You cannot use this function to handle front panel events such as
mouse clicks or keystrokes programmatically. Use the Event structure to
handle front panel events programmatically.

Continual polling can cause a VI to run millions of times and use up system resources
before a user interacts with the front panel. If you use this function, the loop runs only
twice to respond to user input—once to engage the function and a second time when
the user changes the value of a front panel object.

The VI in the following example pauses at the Wait For Front Panel Activity Node until a
user enters a user name or password or clicks the OK button.

1884 ni.com
 Functions

The OK button wired to the While Loop passes the user name and password to the
Validate Password VI and to the do not wait! parameter of the Wait For Front Panel
Activity function. If the button were not wired to the function, clicking the OK button
would execute the subdiagram in the While Loop including the Wait For Front Panel
Activity function, which defaults to wait on front panel activity when executed. The
user would have to click the OK button twice to send the user name and password to
the Validate Password VI—one time to wake up the VI and execute the loop and a
second time to wake up the VI and send the user name and password out of the loop
to the Validate Password VI.

Generate Front Panel Activity Function

Programmatically generates front panel activity so any VI execution halted by the Wait
on Front Panel Activity function continues executing. No actual changes occur on the
front panel.

Inputs/Outputs
• front panel (this VI's panel) —

© National Instruments 1885

 Functions

front panel specifies which VI the function generates front panel activity for. If you do not specify
a reference to a VI, the function generates front panel activity of the VI in which you place the
function.

You must wire a reference to a VI in a local application instance. You cannot wire a reference to a
VI in a remote application instance.

Color Box Constant

Use the color box constant to supply a constant color value to the block diagram.

Use the color picker to set the color in the color box constant.

You cannot change the value of the color box constant while the VI runs. You can assign
a label to this constant.

Listbox Symbol Ring Constant

Use the listbox symbol ring constant to assign symbols to items in a listbox control.

You typically wire the listbox symbol ring constant to the Item Symbols property in a
Property Node for a listbox.

Events

Use the Events functions to register events dynamically and to create user events.

1886 ni.com
 Functions

Palette
Description
Object
Register Dynamically registers events. The events for which you can register depend on the type
For of the reference you wire to each event source input. Wire the event reg refnum out
Events output to an Event structure or to another Register For Events function.
Waits until an event occurs, then executes the appropriate case to handle that event.
The Event structure has one or more subdiagrams, or event cases, exactly one of which
Event executes when the structure executes to handle an event. This structure can time out
Structure while waiting for notification of an event. Wire a value to the Timeout terminal at the
top left of the Event structure to specify the number of milliseconds the Event structure
waits for an event. The default is -1, which indicates never to time out.
Unregister
For
Unregisters all events associated with an event registration refnum.
Events
Function
Flush Discards the least recent notify events from one or more event queues. If the event
Event queue that you want to discard includes filter events, this function stops at the first
Queue filter event in the queue and discards only the events that occurred previous to the
Function stop.
Returns a reference to a user event. LabVIEW uses the user event data type you wire to
Create
determine the event name and data type of the event. Wire the user event out output
User
to a Register For Events function to register for the event. Wire the user event out
Event
output to a Generate User Event function to send the event and associated data to all
Function
Event structures registered for the event.
Generate
User Broadcasts the user event you wire to the user event input and sends the user event
Event and associated event data to each Event structure registered to handle the event.
Function
Destroy
User Releases a user event reference by destroying its associated user event refnum. Any
Event Event structures registered for this user event no longer receive the event.
Function

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Events\

© National Instruments 1887

 Functions

Events.lvproj
• labview\examples\Structures\Event Structure\Event
Structure.lvproj

Register For Events

Dynamically registers events. The events for which you can register depend on the
type of the reference you wire to each event source input. Wire the event reg refnum
out output to an Event structure or to another Register For Events function.

Inputs/Outputs
• event registration refnum —

event registration refnum is a reference to an existing event registration a Register For Events
function created.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• event source —

event source 1..n is a reference to an application, VI, control, or user event. References must be
to local objects. You cannot wire a reference to a remote object.

If you wire an array or cluster of refnums to this input, LabVIEW registers all elements of the array
or cluster for the event.
• event registration refnum —

event reg refnum out returns the reference to a new or existing event registration.

• error out —

1888 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

When using dynamic registration, make sure you have a Register For Events function
for each Event structure.

Each event source input is a reference to an application, VI, control, or user event.
Each kind of event source can produce a variety of events. To specify which event you
want LabVIEW to begin detecting for a particular event source, right-click the data
item for the event source and select the event to detect. After this function executes,
LabVIEW detects, or registers, every repetition of that event that occurs. LabVIEW
stores these events in a queue so that an Event structure can handle the events later in
the VI.

You can wire the event reg refnum out terminal of the Register For Events function to
the dynamic event terminals on the Event structure border, to the Unregister For
Events function, or to the top left input of another Register For Events function. If you
wire the top left input of the Register For Events function, the function modifies the
existing registration information associated with that refnum instead of registering the
event again.

Registered events stay registered until you explicitly unregister them or until the VI that
registered the events finishes running or you abort the VI. If the VI which registered for
events was a subVI, events are unregistered when that VI's top-level VI finishes
execution or is aborted. If you use the Run VI method to execute a subVI that registered
for events, events are unregistered when the subVI finishes execution or is aborted.

Note LabVIEW does not include an event registration refnum on the Controls
palette because the event registration refnum is strictly typed and a generic
version does not exist. You can create an event registration refnum by
configuring a Register For Events function or right-clicking the function and
creating a control or indicator from the shortcut menu. You also can select
the part of the application that includes the event registration refnum and
selecting Edit»Create SubVI to create a subVI from the selection. If you later
modify the Register For Events function and change the type of the event
registration refnum, you must recreate the control or indicator to match.

© National Instruments 1889

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Events\Dynamic

Event Generation.vi

Unregister For Events Function

Unregisters all events associated with an event registration refnum.

Event structures that use this event registration refnum no longer receive any dynamic
events. National Instruments recommends that you unregister for events when you no
longer need to handle them. If you do not unregister for events, LabVIEW continues to
generate and queue the events as long as the VI runs, even if no Event structure is
waiting to handle them, which consumes memory and can hang the VI if you enable
front panel locking for the events.

Inputs/Outputs
• event registration refnum —

event registration refnum is a reference to an existing event registration a Register For Events
function created.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

1890 ni.com
 Functions

Flush Event Queue Function

Discards the least recent notify events from one or more event queues. If the event
queue that you want to discard includes filter events, this function stops at the first
filter event in the queue and discards only the events that occurred previous to the
stop.

Inputs/Outputs
• oldest event time —

oldest event time is the event timestamp, in milliseconds, when you want to start keeping
events. This function discards all events previous to the event time you specify. This millisecond
timer can accept the value returned by the Tick Count (ms) function.

• event registration refnum —

event registration refnum is a reference to an event registration refnum associated with the
queue you want to flush.

• include static events? (T) —

include static events? specifies whether you want to include the enqueued static events
associated with an Event structure in the flush operation. The default is TRUE if you place the
Flush Event Queue function in an event case of an Event structure. Otherwise, the default is
FALSE.

Note If you wire include static events?, you must place this function inside the Event
structure that handles the static events you want to include or omit from the flush
operation.

• event type or object —

© National Instruments 1891

 Functions

event type or object specifies which notify events you want to discard within the criteria set by
oldest event time and keep most recent.

Refer to the Details section for more information about how to specify which events you want to
discard.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• keep most recent —

keep most recent specifies the number of most recent events to keep in the event queue. If you
wire the event type or object parameter, keep most recent affects only the events of the type
you specify. If you flush more than one event queue, keep most recent includes the total
number of events to keep from all specified event queues.

Note If you leave both oldest event time and keep most recent unwired, the
function discards all events in all queues that meet any criteria set by event type or
object. If you wire both oldest event time and keep most recent, this function keeps
all events starting at the event time you specify and all events within the number of
most recent events you specify.

• event reg refnum out —

event reg refnum out returns the event registration refnum associated with the flushed event
queue.

• number of events discarded —

number of events discarded returns the total number of discarded events.

• error out —

error out contains error information. This output provides standard error out functionality.

For applications where events occur in rapid succession but the application only needs
the most recent events, such as Mouse Move or Panel Resize events, you can discard
the older events so the application can respond to the newer event data more quickly.

The following examples show how you can wire data to the event type or object

1892 ni.com
 Functions

parameter to specify the way the Flush Event Queue function discards events.

Example 1: Discarding More than One Event Type

If you want to discard more than one event type, such as Mouse Down and Mouse Up,
you can wire an array or cluster of event type enums to the event type or object input,
as shown in the following example.

Flush Event Queue discards both the Mouse Down and the Mouse Up events regardless
of the event source. However, because a constant value of 1 is wired to the keep most
recent parameter, the function keeps one of the most recent Mouse Down or Mouse Up
events in the event queue. Furthermore, the function keeps only one event total rather
than one event for each event type.

Example 2: Discarding Events Generated by Specific Objects

You can wire a VI Server reference that points to an object that generates an event, a
user event refnum, and any refnum with associated events to the event type or object
input to discard only the events generated by a specific objects. To discard events from
multiple objects, use an array or cluster of refnums, as shown in the following
example.

Flush Event Queue discards any type of event generated by the objects linked to the

© National Instruments 1893

 Functions

references that are bundled in the cluster.

Example 3: Discarding Specific Events Generated by Specific Objects

If you want to discard an event only when a specific object generates that event, you
can bundle an enum that contains the event type you want to discard with a refnum
that points to the object that generates that event. You also can create a cluster or
array of event type enum/object pairs to discard multiple events associated with
multiple objects, as shown in the following example.

• —The function discards the Mouse Up or Mouse Down events only when the
Boolean generates those events.
• —The function discards the Mouse Move event only when the 2D Picture control
generates that event.
• — Because the event is not paired with a specific object, the function discards
the Key Up event when any event source generates that event.

Create User Event Function

Returns a reference to a user event. LabVIEW uses the user event data type you wire to
determine the event name and data type of the event. Wire the user event out output
to a Register For Events function to register for the event. Wire the user event out
output to a Generate User Event function to send the event and associated data to all
Event structures registered for the event.

1894 ni.com
 Functions

Inputs/Outputs
• user event data type —

user event data type is a cluster of elements or an individual element whose data type and label
define the data type and name of the user event.

Note LabVIEW uses owned labels to identify data the user event carries, so label
each element of the input with a descriptive owned label. If you do not add a label,
the user event will not appear in the Event Data Node of an Event structure when
added.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• user event out —

user event out returns the strictly typed user event refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

The user event data type is a cluster of elements or an individual element. If you wire
a cluster to the user event data type input, LabVIEW uses the type name of the cluster
as the name of the user event. The names and data types of the cluster elements
define the event data the user event carries. If you wire an individual data element to
the user event data type input, LabVIEW uses the type name of the element as the
name of the user event and as the name of the single data item it carries, which is the
same data type as the element. The actual value you wire to the function is not
important because LabVIEW uses only the name and data type to define the user
event. The user event out output is a strictly typed refnum that includes the user
event name and event data type.

You can wire the user event out output to the Generate User Event function and the
Destroy User Event function. Wire the user event out output to the Register For Events
function to dynamically register for notification when the user event occurs. When you
handle a user event in an Event structure, the name of the user event appears in the

© National Instruments 1895

 Functions

event selector label at the top of the Event structure, and the user event data fields
appear in the Event Data Node inside the left border of the event case.

Note If you obtain a user event reference in one application instance, you
cannot use that user event reference in another application instance. If you
attempt to use a user event reference in another application instance,
LabVIEW returns error 1500.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Events\User

Event Generation.vi

Generate User Event Function

Broadcasts the user event you wire to the user event input and sends the user event
and associated event data to each Event structure registered to handle the event.

Inputs/Outputs
• priority (normal) —

priority specifies the priority of the user event. If you specify high priority, the Generate
User Event function enqueues the user event and associated event data into the event queue in
front of any previously generated normal priority events. The default is normal priority.

0 high priority
1 normal priority (default)

• user event —

1896 ni.com
 Functions

user event is a user event refnum the Create User Event function created.

• event data —

event data is the type of data you defined in the user event data type input of the Create User
Event function.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• user event out —

user event out returns the strictly typed user event refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

The user event input accepts a user event refnum the Create User Event function
created. The data type of the event data input must match the data type of the user
event. For example, if the data type of the user event input is a string, the data type of
the event data input must also be a string. The event data is the type of data you
defined in the user event data type input of the Create User Event function. If the
event is not registered, the Generate User Event function has no effect.

Destroy User Event Function

Releases a user event reference by destroying its associated user event refnum. Any
Event structures registered for this user event no longer receive the event.

Inputs/Outputs
• user event —

© National Instruments 1897

 Functions

user event is a user event refnum the Create User Event function created.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Menu

Use the Menu functions to modify the menus in LabVIEW applications. Use the
functions located on the top row of the palette to handle menu selections.

(Real-Time Module) You cannot use these functions in VIs that run on RT targets.

Palette Object Description

Current VI's Menubar
Returns the menu reference refnum of the current VI.
Function
Get Menu Selection Returns the item tag of the last selected menu item, optionally waiting ms
Function timeout milliseconds.
Enable Menu Tracking
Enables or disables tracking of menu bar selections.
Function
Insert Menu Items Inserts menu items specified by item names or item tags into a menu or a
Function submenu within the menu.
Delete Menu Items
Deletes menu items from the menu or a submenu within the menu.
Function
Set Menu Item Info
Sets the attributes of a menu item.
Function

1898 ni.com
 Functions

Palette Object Description

Get Menu Item Info
Returns the attributes of a menu item or menu bar.
Function
Get Menu Short Cut Info
Returns the menu item that is accessible through a given shortcut.
Function

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Menu\

Customizing the Menubar

Current VI's Menubar Function

Returns the menu reference refnum of the current VI.

Use the menu reference refnum in conjunction with other Menu functions to
programmatically modify the run-time menu of a VI.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• menu reference —

menu reference refers to the menu bar of the current VI.

Get Menu Selection Function

Returns the item tag of the last selected menu item, optionally waiting ms timeout
milliseconds.

© National Instruments 1899

 Functions

If you use this function with an Event structure configured to handle the same menu
item, the Event structure takes precedence and LabVIEW ignores the Get Menu
Selection function. In any given VI, use the Event structure or the Get Menu Selection
function.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• menu reference —

menu reference is the reference to a menu bar in a VI.

You can obtain this refnum with the Current VI's Menubar function.
• ms timeout (200) —

ms timeout is the maximum amount of time this function checks for a menu selection.

The default is 200 ms. –1 indicates never to time out.

• block menu (F) —

If block menu is TRUE, LabVIEW disables menu tracking after reading an item tag.

After you process the menu selection, you must use the Enable Menu Tracking function to enable
menu tracking. The default is FALSE.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timed out —

If timed out is TRUE, a user selection was not made within the time specified by ms timeout.

• menu reference out —

menu reference out returns menu reference unchanged.

1900 ni.com
 Functions

• item tag —

item tag is the menu item that was selected.

Wire this value to a Case structure selector terminal to handle the menu selection. When you
create a case to handle each menu item, enter application item tags in the case selector label to
handle application menu items.
• item path —

item path describes the position of the item in the menu hierarchy, which is in the format of a
list of menu tags separated by a colon (:).

For example, if you choose the Open menu item from the File menu, the item path is
File:Open.
• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Menu\

Customizing the Menubar\Customizing the Menubar.vi

Enable Menu Tracking Function

Enables or disables tracking of menu bar selections.

If you use the Get Menu Selection function to block a menu, you must use this function
to enable the menu.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

© National Instruments 1901

 Functions

Inputs/Outputs
• menu reference —

menu reference is the reference to a menu bar in a VI.

You can obtain this refnum with the Current VI's Menubar function.
• enable (T) —

enable allows you to perform menu tracking if enable is TRUE (default). If enable is FALSE, menu
tracking is disabled.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• menu reference out —

menu reference out returns menu reference unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Insert Menu Items Function

Inserts menu items specified by item names or item tags into a menu or a submenu
within the menu.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• menu tag —

1902 ni.com
 Functions

menu tag specifies the submenu in which to insert the items.

If you do not specify menu tag, the function inserts the items at the top level of the menu.
• menu reference —

menu reference is the reference to a menu bar in a VI or to a shortcut menu of a control. You can
obtain this refnum with the Current VI's Menubar function or with the MenuRef event data field
of menu events.

• item names —

item names identifies the items to insert in the menu. item names is the string that appears in
the menu. You can wire either item names or item tags, in which case both names and tags have
the same values. If you want to insert only one item, wire a string to item names.

• item tags —

item tags identifies the items to insert in the menu. item tags is the string that is returned if the
menu item is selected. You can wire either item names or item tags, in which case both names
and tags have the same values. If you want to insert only one item, wire a string to item tags.

Use application item tags to insert application menu items.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• after item —

after item specifies the position where the items are inserted. after item can be a tag (string) of
an existing item or a position index (zero based integer) in the menu. To insert at the beginning
of the menu, wire a number less than 0 to after item. To insert at the end of the menu, wire a
number larger than the number of items in the menu. You can insert application items using
application tags. You can insert a separator using the application tag APP_SEPARATOR. The
function always ensures that the tags of all the inserted menu items are unique to the menu
hierarchy by appending numbers to the supplied tags, if necessary.

• menu reference out —

menu reference out returns menu reference unchanged.

• item tags out —

© National Instruments 1903

 Functions

item tags out returns the actual tags of the inserted items. If the function does not find menu
tag or after item (tag), the function returns an error.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Menu\

Customizing the Menubar\Customizing the Menubar.vi

Delete Menu Items Function

Deletes menu items from the menu or a submenu within the menu.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• menu reference —

menu reference is the reference to a menu bar in a VI or to a shortcut menu of a control.

You can obtain this refnum with the Current VI's Menubar function or with the MenuRef event
data field of menu events.

• menu tag —

menu tag specifies the submenu from which to delete items.

If you do not specify menu tag, the function deletes all items from the menu.

1904 ni.com
 Functions

• items —

items can be a tag (string) of an existing item, an array of tags of existing items, a position index
(zero-based integer) of an item in the menu, or an array of position indexes of items in the menu.

The default is to delete all the items in the menu or submenu specified by menu tag. If any of the
specified items have a submenu, the function deletes the submenu and all its contents. Use
application item tags for menus or shortcut menus to delete application menu items. Because
separators do not have unique tags, you can delete them using their positional indexes.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• menu reference out —

menu reference out returns menu reference unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Menu\

Customizing the Menubar\Customizing the Menubar.vi

Set Menu Item Info Function

Sets the attributes of a menu item.

Unwired attributes remain unchanged.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

© National Instruments 1905

 Functions

Inputs/Outputs
• item tag —

item tag identifies the menu item you want to set attributes for.

If item tag is not valid, the function returns an error. Use application item tags to set attributes
for application menu items.
• menu reference —

menu reference is the reference to a menu bar in a VI or to a shortcut menu of a control.

You can obtain this refnum with the Current VI's Menubar function or with the MenuRef event
data field of menu events.
• item name —

item name is the string that appears in the menu.

• enabled —

If enabled is FALSE, the menu item is grayed out.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• checked —

If checked is TRUE, the menu item has a checkmark next to it.

• short cut —

short cut is the keyboard equivalent of selecting the menu item with a mouse.

• include Shift key? —

1906 ni.com
 Functions

If include Shift key? is TRUE, the shortcut includes the <Shift> key, in addition to the
shortcut key.

• include Ctrl key? —

If include Ctrl key? is TRUE, the shortcut includes the <Ctrl> key, in addition to the shortcut
key. You can set include Ctrl key? to FALSE only if you select a function key, such as <F1>,
<F2>, and so on, as the shortcut key.

(macOS) The key included is <Command>. (Linux) The key included is <Alt>.
• shortcut key —

shortcut key describes the key associated with the shortcut.

• menu reference out —

menu reference out returns menu reference unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Menu Item Info Function

Returns the attributes of a menu item or menu bar.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• item tag —

© National Instruments 1907

 Functions

item tag identifies the item whose attributes you want to return.

The default is to return the menu bar attributes.

Use application item tags to return application menu item attributes.

• menu reference —

menu reference is the reference to a menu bar in a VI or to a shortcut menu of a control.

You can obtain this refnum with the Current VI's Menubar function or with the MenuRef event
data field of menu events.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• submenu tags —

submenu tags are the submenu item tags if the item has a submenu.

• menu reference out —

menu reference out returns menu reference unchanged.

• item name —

item name is the string that appears in the menu.

• enabled —

If enabled is FALSE, the menu item is grayed out.

• error out —

error out contains error information. This output provides standard error out functionality.

• checked —

If checked is TRUE, the menu item has a checkmark next to it.

• short cut —

short cut is the keyboard equivalent of selecting this menu item with a mouse.

1908 ni.com
 Functions

• include Shift key? —

If include Shift key? is TRUE, the shortcut includes the <Shift> key, in addition to the
shortcut key.

• include Ctrl key? —

If include Ctrl key? is TRUE, the shortcut includes the <Ctrl> key, in addition to the shortcut
key. You can set include Ctrl key? to FALSE only if you select a function key, such as <F1>,
<F2>, and so on, as the shortcut key. On macOS, the key included is <Command>. On Linux,
the key included is <Alt>.

• shortcut key —

shortcut key describes the key associated with the shortcut.

Get Menu Short Cut Info Function

Returns the menu item that is accessible through a given shortcut.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• menu reference —

menu reference is the reference to a menu bar in a VI.

You can obtain this refnum with the Current VI's Menubar function.
• short cut —

short cut is the keyboard equivalent of selecting the menu item with a mouse.

• include Shift key? —

© National Instruments 1909

 Functions

If include Shift key? is TRUE, the shortcut includes the <Shift> key, in addition to the
shortcut key.

• include Ctrl key? —

If include Ctrl key? is TRUE, the shortcut includes the <Ctrl> key, in addition to the shortcut
key. You can set include Ctrl key? to FALSE only if you select a function key, such as <F1>,
<F2>, and so on, as the shortcut key. (macOS) The key included is <Command>. (Linux) The
key included is <Alt>.

• shortcut key —

shortcut key describes the key associated with the shortcut.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• menu reference out —

menu reference out returns menu reference unchanged.

• item tag —

item tag is the tag of the menu item that matches the shortcut.

• item path —

item path describes the position of the item in the menu hierarchy, which is in the format of a
list of menu tags separated by a colon (:).

For example, on Windows, if you do not change the default shortcuts and you pass in <Ctrl-O>
from the menu bar reference of a VI, item path returns File:Open.

• error out —

error out contains error information. This output provides standard error out functionality.

1910 ni.com
 Functions

Cursor

Use the Cursor VIs to change the appearance of the cursor on the front panel of a VI.
For example, if the VI is acquiring or analyzing data and can accept no user input, you
might want to change the cursor to an hourglass or watch cursor. After the VI finishes
acquiring or analyzing data and can accept user input, you can change the cursor back
to the default cursor.

(Real-Time Module) You cannot use these VIs in VIs that run on RT targets.

Palette
Description
Object
Create
Cursor Returns a reference to a cursor in a cursor file.
From File

Changes the appearance of the cursor on the front panel of a VI. Wire data to the icon
Set Cursor
input to determine the polymorphic instance to use or manually select the instance.

Destroy Closes a reference to a cursor and changes the cursor to the default cursor in any VIs
Cursor using the reference.

Changes the appearance of the cursor on the front panel of a VI to the system busy
Set Busy
cursor. You also can use this VI to disable the mouse and keyboard on the front panel.

Changes the appearance of the cursor on the front panel of a VI from a busy cursor to
Unset Busy
the default LabVIEW cursor and enables the mouse on the front panel.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 1911

 Functions

• labview\examples\Dialog and User Interface\Cursor\

Cursor.lvproj

Create Cursor From File

Returns a reference to a cursor in a cursor file.

If a VI that you want to distribute as a stand-alone application or as a shared library

uses a cursor from a cursor file, you must distribute the cursor file with the application
or shared library.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• cursor file —

cursor file is the path to the file that contains the cursor for which you want a reference.

If the file does not exist or if the file is not a valid cursor file, LabVIEW returns error code 7.

(Windows) The file must have a .ani or .cur extension.

(macOS) The file must be a resource file. You also must wire the ID of the cursor you want to use
to the cursor resource ID input. If the cursor image is larger than 16 × 16 pixels, the VI crops the
image to that size.

(Linux) The file must have a .png extension. You cannot use animated cursors. Cursors are
monochrome, and the shape of the cursor is determined by the how you set the transparency
around the .png file.

• cursor resource ID —

(macOS) cursor resource ID is the ID for a cursor in the resource file wired to cursor file.

If the cursor is animated, cursor resource ID must be less than 128. If the cursor is not

1912 ni.com
 Functions

animated, cursor resource ID must be equal to or greater than 128.

• hotspot —

hotspot contains the coordinates of the cursor hot spot starting from the upper left corner. You
cannot set the hot spot for animated cursors.

National Instruments recommends that you set the hot spot only on Linux. Windows and macOS
cursors already have hot spots, but you must set the hot spot for cursors on Linux.

• x—

x is the horizontal coordinate of the hot spot, which increases to the right. The default is –1,
which means the VI sets the horizontal coordinate of the hot spot to the horizontal
coordinate of the default hot spot for the cursor.

• y—

y is the vertical coordinate of the hot spot, which increases to the bottom. The default is –1,
which means the VI sets the vertical coordinate of the hot spot to the vertical coordinate of
the default hot spot for the cursor.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• cursor ID —

cursor ID is a reference to the cursor in the cursor file. If a reference to the cursor already exists,
the VI returns the existing reference.

Wire this reference to the Set Cursor or Set Busy VIs to change the appearance of the cursor on
the front panel of the VI.

Use the Destroy Cursor VI to close the cursor reference after you set the cursor.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1913

 Functions

Set Cursor

Changes the appearance of the cursor on the front panel of a VI. Wire data to the icon
input to determine the polymorphic instance to use or manually select the instance.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

• Set Cursor (Icon Pict) VI

• Set Cursor (Cursor ID) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Cursor\Change

Cursor Icon.vi

Set Cursor (Icon Pict) VI

Changes the appearance of the cursor on the front panel of a VI. Wire data to the icon
input to determine the polymorphic instance to use or manually select the instance.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• icon —

icon is the system or LabVIEW cursor you want to use on the front panel of the VI.

1914 ni.com
 Functions

Uses the default LabVIEW cursor. For example, if automatic tool selection is enabled and you
0 move the cursor over a ring control, LabVIEW uses the cursor of the Operating tool. If you
move the cursor over a string control, LabVIEW uses the cursor of the Labeling tool.
(Windows) LabVIEW uses this system cursor. (macOS and Linux) LabVIEW uses the system
1
cursor that corresponds to this Windows cursor.
(Windows) LabVIEW uses this system cursor. (macOS and Linux) LabVIEW uses the system
2
cursor that corresponds to this Windows cursor.
(Windows) LabVIEW uses this system cursor. (macOS and Linux) LabVIEW uses the system
3
cursor that corresponds to this Windows cursor.
(Windows) LabVIEW uses this system cursor. (macOS and Linux) LabVIEW uses the system
4
cursor that corresponds to this Windows cursor.
(Windows) LabVIEW uses this system cursor. (macOS and Linux) LabVIEW uses the system
5
cursor that corresponds to this Windows cursor.
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

© National Instruments 1915

 Functions

31
32

• VI reference (current VI) —

VI reference is a reference to the VI for which you want to change the cursor. The default is a
reference to the current VI.

You can use the Open VI Reference function to obtain a reference to another VI.

This input is useful if multiple front panels are open, but you want to change the cursor in only
one front panel. If the front panel of the VI for which you want to change the cursor is not open,
this VI returns an error.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• previous cursor ID —

previous cursor ID is a reference to the cursor on the front panel before this VI ran.

Wire this output to another instance of the Set Cursor VI to change the cursor back to the
previous cursor.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Cursor\Change

Cursor Icon.vi

Set Cursor (Cursor ID) VI

Changes the appearance of the cursor on the front panel of a VI. Wire data to the icon

1916 ni.com
 Functions

input to determine the polymorphic instance to use or manually select the instance.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• cursor ID —

cursor ID is a reference to the cursor you want to use on the front panel of the VI.

Use the Create Cursor From File VI to obtain a reference to a cursor.

If the cursor reference is invalid, LabVIEW changes the cursor to the default LabVIEW cursor and
returns control of the cursor to LabVIEW.

• VI reference (current VI) —

VI reference is a reference to the VI for which you want to change the cursor. The default is a
reference to the current VI.

You can use the Open VI Reference function to obtain a reference to another VI.

This input is useful if multiple front panels are open, but you want to change the cursor in only
one front panel. If the front panel of the VI for which you want to change the cursor is not open,
this VI returns an error.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• previous cursor ID —

previous cursor ID is a reference to the cursor on the front panel before this VI ran.

Wire this output to another instance of the Set Cursor VI to change the cursor back to the
previous cursor.

• error out —

© National Instruments 1917

 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Cursor\Change

Cursor Icon.vi

Destroy Cursor

Closes a reference to a cursor and changes the cursor to the default cursor in any VIs
using the reference.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• cursor ID —

cursor ID is the cursor reference you want to close.

Use the Create Cursor From File VI to create this reference.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

1918 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Cursor\Change

Cursor Icon.vi

Set Busy

Changes the appearance of the cursor on the front panel of a VI to the system busy
cursor. You also can use this VI to disable the mouse and keyboard on the front panel.

Use the Unset Busy VI to change the cursor back to the default LabVIEW cursor and to
enable the mouse and keyboard again. Using the Set Busy VI is similar to using the Set
Cursor VI and wiring 1 to the icon input.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• cursor ID —

cursor ID is a reference to the cursor you want to use on the front panel of the VI. The default is
the system busy cursor.

Use the Create Cursor From File VI to obtain a reference to a cursor.

If the cursor reference is invalid, LabVIEW changes the cursor to the default LabVIEW cursor and
returns control of the cursor to LabVIEW.

• VI reference (current VI) —

VI reference is a reference to the VI for which you want to change the cursor. The default is a
reference to the current VI.

© National Instruments 1919

 Functions

You can use the Open VI Reference function to obtain a reference to another VI.

This input is useful if multiple front panels are open, but you want to change the cursor in only
one front panel. If the front panel of the VI for which you want to change the cursor is not open,
this VI returns an error.

• disable click? (T) —

If disable click? is TRUE (default), the VI disables the mouse and keyboard on the front panel.

You must use the Unset Busy VI to enable the mouse and keyboard again.

If you disable the mouse and keyboard on the front panel, the user still can click the Abort
Execution button on the toolbar.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• previous cursor ID —

previous cursor ID is a reference to the cursor on the front panel before this VI ran.

Wire this output to the Set Cursor VI to change the cursor back to the previous cursor.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Cursor\Set

Busy Cursor.vi

Unset Busy

Changes the appearance of the cursor on the front panel of a VI from a busy cursor to
the default LabVIEW cursor and enables the mouse on the front panel.

1920 ni.com
 Functions

Use this VI only after you use the Set Busy VI.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• VI reference (current VI) —

VI reference is a reference to the VI for which you want to change the cursor. The default is a
reference to the current VI.

You can use the Open VI Reference function to obtain a reference to another VI.

This input is useful if multiple front panels are open, but you want to change the cursor in only
one front panel. If the front panel of the VI for which you want to change the cursor is not open,
this VI returns an error.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Dialog and User Interface\Cursor\Set

Busy Cursor.vi

© National Instruments 1921

 Functions

Help

Use the Help VI and functions to link from VIs to HTML files or compiled help files.

(Real-Time Module) You cannot use the objects on this palette in VIs that run on RT
targets.

Palette
Description
Object
Control
Help
Modifies the Context Help window by showing, hiding, or by repositioning the window.
Window
Function
Get Help
Window
Returns the status and the position of the Context Help window.
Status
Function
Control
Online Controls a compiled help file by displaying the table of contents, jumping to a specific
Help topic in the file, or closing the help file.
Function

Open Displays a URL or HTML file in the default Web browser. If the URL or path you wire to this
URL in VI contains a space character, the VI encodes the space as %20 before displaying the URL
Default or HTML file in the Web browser. Wire data to the URL input to determine the
Browser polymorphic instance to use or manually select the instance.

Control Help Window Function

Modifies the Context Help window by showing, hiding, or by repositioning the window.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

1922 ni.com
 Functions

Inputs/Outputs
• Show —

If Show is TRUE, LabVIEW displays the Context Help window. If FALSE, LabVIEW hides the
Context Help window. The default is to maintain the current visibility of the Context Help
window.

• Top Left Corner —

Top Left Corner indicates the new position of the Context Help window and contains numbers
that represent points offset from the upper left corner of the screen.

• Horizontal —

Horizontal is the number of points to place the Context Help window to the right of the
upper left corner of the screen.

• Vertical —

Vertical is the number of points to place the Context Help window below the upper left
corner of the screen.

Get Help Window Status Function

Returns the status and the position of the Context Help window.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• Show —

© National Instruments 1923

 Functions

If Show is TRUE, the Context Help window is visible.

If FALSE, the Context Help window is not visible.

• Top Left Corner —

Top Left Corner indicates the position of the Context Help window and contains numbers that
represent points offset from the upper left corner of the screen.

• Horizontal —

Horizontal is the number of points that the Context Help window is to the right of the upper
left corner of the screen.

• Vertical —

Vertical is the number of points that the Context Help window is below the upper left corner
of the screen.

Control Online Help Function

Controls a compiled help file by displaying the table of contents, jumping to a specific
topic in the file, or closing the help file.

You can create a compiled help file and use this function to link from a VI to the help
file. You also can use this function to display an HTML file in the default browser.

(Real-Time Module) You cannot use this function in VIs that run on RT targets.

Inputs/Outputs
• Operation —

Operation is the operation to perform on the help file.

1924 ni.com
 Functions

Contents—Displays the table of contents of the help file. If you use this function to control a
0 .chm file, setting this input to 0 displays the table of contents, index, or search tab, depending
on which tab was visible the last time you closed the .chm file.
Key—Displays a specific topic in the help file using a keyword in the help file index or using the
1
name of an individual HTML file in the compiled help file.
2 Close—Closes the help file.

• String to search for —

String to search for is the index keyword or HTML filename for the topic in the help file that you
want to display.

The default is an empty string. LabVIEW ignores this string if Operation is 0 or 2.

If this string contains an index keyword, the string must match the index keyword as it appears in
the help file index. To jump to a topic with a multi-level index keyword, enter the first-level index
keyword, a colon, and the second-level index keyword. Do not separate the elements with
spaces. For example, a error codes:GPIB string jumps to a topic with a first-level index
keyword of error codes and a second-level index keyword of GPIB.

If Path to the help file contains a path to an HTML Help (.chm) file, this string can contain the
filename (.htm or .html) of an individual HTML file in the HTML Help project.

• Path to the help file —

Path to the help file is the path or symbolic path to the compiled help file you want to control.

The help file can have a .chm or .hlp extension. (macOS and Linux) If this input contains a
path to a .chm file and the file does not exist, LabVIEW ignores this input. However, if String to
search for contains an HTML filename and that HTML file is in the help\html\help.chm
directory where help.chm is the filename you wire to this input, LabVIEW displays that HTML
file in the default browser. If this input contains a path to a .chm file and String to search for
contains an index keyword, this function does not display an HTML file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1925

 Functions

Open URL in Default Browser

Displays a URL or HTML file in the default Web browser. If the URL or path you wire to
this VI contains a space character, the VI encodes the space as %20 before displaying
the URL or HTML file in the Web browser. Wire data to the URL input to determine the
polymorphic instance to use or manually select the instance.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

• Open URL in Default Browser (string) VI

• Open URL in Default Browser (path) VI

Open URL in Default Browser (string) VI

Displays a URL or HTML file in the default Web browser. If the URL or path you wire to
this VI contains a space character, the VI encodes the space as %20 before displaying
the URL or HTML file in the Web browser. Wire data to the URL input to determine the
polymorphic instance to use or manually select the instance.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• URL —

URL is the URL you want to display in the default Web browser.

For example, wire http://www.site.com/report.html to this input to display the HTML

file report.html on the Web Server www.site.com in the browser.

• error in (no error) —

1926 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• URL out —

URL out is the URL displayed in the Web browser.

• error out —

error out contains error information. This output provides standard error out functionality.

Open URL in Default Browser (path) VI

Displays a URL or HTML file in the default Web browser. If the URL or path you wire to
this VI contains a space character, the VI encodes the space as %20 before displaying
the URL or HTML file in the Web browser. Wire data to the URL input to determine the
polymorphic instance to use or manually select the instance.

(Real-Time Module) You cannot use this VI in VIs that run on RT targets.

Inputs/Outputs
• path —

path is the path to the HTML file you want to display in the default Web browser.

If the path is relative, the VI interprets the path as relative to the application directory, such as
the labview directory or the directory containing the stand-alone application.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• URL out —

© National Instruments 1927

 Functions

URL out is the URL displayed in the Web browser.

• error out —

error out contains error information. This output provides standard error out functionality.

Synchronization
Use the Synchronization VIs and functions to synchronize tasks executing in parallel
and to pass data between parallel tasks.

Palette
Description
Object

Use the Notifier Operations functions to suspend the execution of a block diagram
Notifier
until you receive data from another section of the block diagram or from another VI
Operations
running in the same application instance.

Queue Use the Queue Operations functions to create a queue for communicating data
Operations between sections of a block diagram or from another VI.

Use the Semaphore VIs to limit the number of tasks that can simultaneously operate
on a shared (protected) resource. A protected resource or critical section of code
Semaphore
might include writing to global variables or communicating with external
instruments.

Use the Rendezvous VIs to synchronize two or more separate, parallel tasks at
specific points of execution. Each task that reaches the rendezvous waits until the
Rendezvous
specified number of tasks are waiting, at which point all tasks proceed with
execution.

1928 ni.com
 Functions

Palette
Description
Object

Occurrences Use the Occurrences functions to control separate, synchronous activities.

Indicates that a subVI or section of a block diagram is running for the first time. The
First Call?
First Call? function returns TRUE only the first time you call it after you click the Run
Function
button.

Passes through the values of the input wires after the upstream code executes.
Synchronize
Data Flow Use this VI to synchronize multiple parallel code paths at a single point of data flow to
ensure a certain execution order.

Notifier Operations

Use the Notifier Operations functions to suspend the execution of a block diagram
until you receive data from another section of the block diagram or from another VI
running in the same application instance.

You cannot use notifiers to communicate with VIs on other computers. For example,
you cannot use notifiers to communicate across a network or the VI Server.

Unlike the Queue Operations functions, the Notifier Operations functions do not buffer
sent messages. If no nodes are waiting on a message when it is sent, the data is lost if
another message is sent. Notifiers behave like single-element, bounded, lossy queues.

When using a Notifier Operation function in a While Loop, the stop condition should be
connected to the execution of the function.

Palette Object Description

Obtain Notifier
Returns a reference to a notifier.
Function

© National Instruments 1929

 Functions

Palette Object Description

Send Notification
Sends a message to all functions waiting on a notifier.
Function
Cancel Notification Erases any message currently in a notifier and returns the cancelled
Function message.
Get Notifier Status Returns information about the current state of a notifier, such as the last
Function uncancelled notification sent to the notifier.
Release Notifier
Releases a reference to a notifier.
Function
Wait on Notification
Waits until a notifier receives a message.
Function
Wait on Notification
from Multiple Waits until at least one of the notifiers you specify receives a message.
Function

Use the Advanced Notifier Waiting functions to prevent dropped messages

Advanced Notifier
and other problems when you use the functions repeatedly with different
Waiting
notifiers.

Obtain Notifier Function

Returns a reference to a notifier.

Use this reference when calling other Notifier Operations functions.

Inputs/Outputs
• name (unnamed) —

name contains the name of the notifier that you want to obtain or create.

The default is an empty string to create an unnamed notifier.

1930 ni.com
 Functions

• element data type —

element data type is the type of data that you want the notifier to contain.

You can wire any data type to this input.

• create if not found? (T) —

create if not found? specifies whether you want to create a new notifier if one with the same
name as name does not exist.

If TRUE (default), the function creates a notifier if one with the same name does not exist.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifier out —

notifier out is a reference to the existing named notifier or the new notifier created by this
function.

• created new? —

created new? is TRUE if the function created a new notifier.

• error out —

error out contains error information. This output provides standard error out functionality.

Use named notifiers to pass data between two sections of a block diagram or between
two VIs. If you do not wire name, the function creates a new, unnamed notifier
reference. If you wire name, the function first searches for an existing notifier with the
same name and returns a new reference to the existing notifier. If a notifier with the
same name does not already exist and create if not found? is TRUE, the function
creates a new, named notifier reference.

If you use the Obtain Notifier function to return a reference to a named notifier inside a
loop, LabVIEW creates a new reference to the named notifier each time the loop
iterates. If you use Obtain Notifier in a tight loop, LabVIEW slowly increases how much
memory it uses because each new reference uses an additional four bytes. These bytes
are released automatically when the VI stops running. However, in a long-running

© National Instruments 1931

 Functions

application it may appear as if LabVIEW is leaking memory since the memory usage
keeps increasing. To prevent this unintended memory allocation, use the Release
Notifier function in the loop to release the notifier reference for each iteration.

This function might return error codes 1, 2, 1094, 1100, or 1492.

Note If you obtain a notifier reference in one application instance, you

cannot use that notifier reference in another application instance. If you
attempt to use a notifier reference in another application instance, LabVIEW
returns error 1492.

Send Notification Function

Sends a message to all functions waiting on a notifier.

All Wait on Notification and Wait on Notification from Multiple functions currently
waiting on the notifier stop waiting and continue to execute.

Inputs/Outputs
• notifier —

notifier is a reference to a notifier.

Use the Obtain Notifier function to obtain a notifier reference.

• notification —

notification is the message to send.

This data type changes to match the subtype of notifier.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifier out —

1932 ni.com
 Functions

notifier out returns notifier unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Notifier\Simple
Notifier.vi

Cancel Notification Function

Erases any message currently in a notifier and returns the cancelled message.

Inputs/Outputs
• notifier —

notifier is a reference to a notifier.

Use the Obtain Notifier function to obtain a notifier reference.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifier out —

notifier out returns notifier unchanged.

• canceled notification —

© National Instruments 1933

 Functions

cancelled notification contains the last notification sent to the notifier.

This data type changes to match the subtype of notifier.

• error out —

error out contains error information. This output provides standard error out functionality.

If any Wait on Notification or Wait on Notification from Multiple functions received the
message before the call to this function, those functions continue to execute. This
function does not recall or reset any wait functions. After you cancel a notification, any
subsequent wait functions wait until the notifier receives another message. Canceling
a notification before the notifier has a message does not result in an error.

Get Notifier Status Function

Returns information about the current state of a notifier, such as the last uncancelled
notification sent to the notifier.

Inputs/Outputs
• notifier —

notifier is a reference to a notifier.

Use the Obtain Notifier function to obtain a notifier reference.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifier name —

1934 ni.com
 Functions

notifier name specifies the name of the notifier.

• notifier out —

notifier out returns notifier unchanged.

• latest notification —

latest notification is the most recent uncancelled notification sent to the notifier.

If no notification is available, the function returns the zero value for the element data type you
wired in the Obtain Notifier function.

This data type changes to match the subtype of notifier.

• # waiting —

# waiting is the number of functions currently waiting on the notifier.

These functions include Wait on Notification and Wait on Notification from Multiple.
• error out —

error out contains error information. This output provides standard error out functionality.

Release Notifier Function

Releases a reference to a notifier.

Inputs/Outputs
• notifier —

notifier is a reference to a notifier.

Use the Obtain Notifier function to obtain a notifier reference.

• force destroy? (F) —

© National Instruments 1935

 Functions

force destroy? indicates whether to destroy the notifier.

If FALSE (default) and you want to destroy the notifier, call the Release Notifier function a
number of times equal to the number of times you obtained a reference to the notifier or stop all
VIs using the notifier reference. If TRUE, the function destroys the notifier and you do not have to
call the function multiple times or stop all VIs using the notifier reference.
• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• notifier name —

notifier name specifies the name of the notifier.

• last notification —

last notification is the last uncancelled notification sent to the notifier.

If no notification is available, the function returns the zero value for the element data type you
wired in the Obtain Notifier function.

This data type changes to match the subtype of notifier.

• error out —

error out contains error information. This output provides standard error out functionality.

You can use the Obtain Notifier function to obtain a reference to the same notifier with
the same name multiple times. To destroy a notifier, call the Release Notifier function a
number of times equal to the number of times you obtained a reference to the notifier
or stop all VIs using the notifier reference.

If force destroy? is TRUE, this function releases all references to the notifier and
destroys the notifier.

Any Wait on Notification or Wait on Notification from Multiple functions waiting on the
notifier time out and return error code 1122.

1936 ni.com
 Functions

Wait on Notification Function

Waits until a notifier receives a message.

When the notifier receives a message, this function continues to execute. Use the Send
Notification function to send the message. If a notifier reference becomes invalid such
as when another function closes it, the function stops waiting and returns error code
1122. If the notifier does not contain a message, this function waits until the notifier
receives a message.

Inputs/Outputs
• notifier —

notifier is a reference to a notifier.

Use the Obtain Notifier function to obtain a notifier reference.

• ignore previous (F) —

ignore previous indicates whether to ignore messages that LabVIEW sends to the notifier before
it calls this function.

If TRUE and the notifier contains a message before you call this function, this function waits until
the notifier receives another message. If FALSE (default) and the notifier contains a message
before you call this function, this function continues to execute.
• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for the notifier to
receive a message.

The default is –1, which indicates never to time out.

If the function waits timeout in ms and the notifier does not receive a message, timed out? is
TRUE.

• error in (no error) —

© National Instruments 1937

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifier out —

notifier out returns notifier unchanged.

• notification —

notification is the last message the notifier receives.

This data type changes to match the subtype of notifier.

• timed out? —

timed out? is TRUE if the notifier does not receive a message before the function times out or if
an error occurs.

• error out —

error out contains error information. This output provides standard error out functionality.

Each unique instance of this function remembers the timestamp of the last message it
receives.

If ignore previous is FALSE, each instance of the Wait on Notification function waits if
the message in the notifier has a time stamp for the same time that the instance of the
function last executed. If the message is new, then the function returns the message.

When ignore previous is TRUE, the Wait on Notification function always waits for a
new message, even if the message currently in the notifier is one it has never seen
before.

If you experience deadlock when you use this function repeatedly with different
notifiers, use the Wait on Notification with Notifier History function to store
timestamps for each individual notifier. This function prevents deadlock.

This function does not remove the message from the notifier. Although a specific
instance of the function returns a message only once, other instances of the function
or to the Wait on Notification from Multiple function repeat the message until you call
the Send Notification function with a new message.

1938 ni.com
 Functions

Wait on Notification from Multiple Function

Waits until at least one of the notifiers you specify receives a message.

When one of the notifiers receives a message, this function continues to execute. Use
the Send Notification function to send the message. If a notifier reference becomes
invalid, such as when another function closes it, this function stops waiting and
returns error code 1122. If the notifier does not contain a message, this function waits
until the notifier receives a message.

Inputs/Outputs
• notifiers —

notifiers is an array of notifier references.

Use the Obtain Notifier function to obtain a notifier reference.

• ignore previous (F) —

ignore previous indicates whether to ignore messages that LabVIEW sends to the notifier before
it calls this function.

If TRUE and the notifier contains a message before you call this function, this function waits until
the notifier receives another message. If FALSE (default) and the notifier contains a message
before you call this function, this function continues to execute.
• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for the notifier to
receive a message.

The default is –1, which indicates never to time out.

If the function waits timeout in ms and the notifier does not receive a message, timed out? is
TRUE.

• error in (no error) —

© National Instruments 1939

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifiers out —

notifiers out returns an array of the notifier references from which messages were received.

• notifications —

notifications is an array of the last messages the notifiers receive.

This data type changes to match the subtype of notifiers, unless the subtype is an array. If the
subtype is an array, the data type becomes a cluster of arrays.
• timed out? —

timed out? is TRUE if the notifier does not receive a message before the function times out or if
an error occurs.

• error out —

error out contains error information. This output provides standard error out functionality.

Use the Wait on Notification function for a single notifier reference.

Each unique instance of this function remembers the time stamp of the last message it
receives. If this function receives only one message, the function stops remembering
which message the time stamp refers to, and the only item filled in the notifiers array is
the first element.

If you experience deadlock when you use this function repeatedly with different
notifiers, use the Wait on Notification from Multiple with Notifier History function to
store time stamps for each individual notifier. This function prevents deadlock.

If ignore previous is FALSE, each instance of the Wait on Notification from Multiple
function determines if one or more notifier has a message newer than the time stamp
most recently received by this function. If one or more of the notifiers has new
messages, all messages are returned.

When ignore previous is TRUE, this function always waits for a new message, even if
the message currently in the notifier is one it has never seen before.

1940 ni.com
 Functions

This function does not remove the message from the notifier. Although a specific
instance of the function returns a message only once, other instances of the function
or to the Wait on Notification function repeat the message until you call the Send
Notification function with a new message.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Notifier\Wait on
Multiple Notifiers.vi

Advanced Notifier Waiting

Use the Advanced Notifier Waiting functions to prevent dropped messages and other
problems when you use the functions repeatedly with different notifiers.

Palette Object Description

Wait on Notification Waits until a notifier receives a message. This function tracks the most
with Notifier History recent message and timestamp for each individual notifier when you use
Function this function repeatedly with different notifiers.
Wait on Notification
Waits until a notifier within an array receives a message. This function
from Multiple with
tracks the most recent message and timestamp for each individual
Notifier History
notifier within an array.
Function

Wait on Notification with Notifier History

Function
Waits until a notifier receives a message. This function tracks the most recent message
and timestamp for each individual notifier when you use this function repeatedly with
different notifiers.

© National Instruments 1941

 Functions

Inputs/Outputs
• notifier —

notifier is a reference to a notifier.

Use the Obtain Notifier function to obtain a notifier reference.

• ignore previous (F) —

ignore previous indicates whether to ignore messages that LabVIEW sends to the notifier before
it calls this function.

If TRUE and the notifier contains a message before you call this function, this function waits until
the notifier receives another message. If FALSE (default) and the notifier contains a message
before you call this function, this function continues to execute.
• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for the notifier to
receive a message.

The default is –1, which indicates never to time out.

If the function waits timeout in ms and the notifier does not receive a message, timed out? is
TRUE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifier out —

notifier out returns notifier unchanged.

• notification —

notification is the last message the notifier receives.

This data type changes to match the subtype of notifier.

• timed out? —

1942 ni.com
 Functions

timed out? is TRUE if the notifier does not receive a message before the function times out or if
an error occurs.

• error out —

error out contains error information. This output provides standard error out functionality.

Each unique instance of this function remembers the timestamp of the most recent
message that each individual notifier receives.

Maintaining notifier history prevents dropped messages and other problems when you
use this function repeatedly with different notifiers. When the notifier receives a
message, this function continues to execute. Use the Send Notification function to
send the message. If a notifier reference becomes invalid when another function closes
it, the function stops waiting and returns error code 1122. If the notifier does not
contain a message, this function waits until the notifier receives a message.

Maintaining notifier history also causes this function to run slower than the Wait on
Notification function. The Wait on Notification function does not maintain notifier
history and might experience deadlock when you use it repeatedly with different
notifiers.

Use the Wait on Notification from Multiple with Notifier History function to handle an
array of notifier references.

If ignore previous is FALSE, each instance of the Wait on Notification with Notifier
History function waits if it has not received notification. The function also waits if the
timestamp of the current message is the same as when the instance of the function
last executed. If the message is new, then the function returns the message.

If ignore previous is TRUE, the Wait on Notification with Notifier History function
always waits for a new message, even if the message currently in the notifier is one the
function has never seen before.

This function does not remove the message from the notifier. Although a single
instance of the function returns a message only once, other instances of the function
or the Wait on Notification from Multiple function repeat the message until you call the

© National Instruments 1943

 Functions

Send Notification function with a new message.

Wait on Notification from Multiple with

Notifier History Function
Waits until a notifier within an array receives a message. This function tracks the most
recent message and timestamp for each individual notifier within an array.

Inputs/Outputs
• notifiers —

notifiers is an array of notifier references.

Use the Obtain Notifier function to obtain a notifier reference.

• ignore previous (F) —

ignore previous indicates whether to ignore messages that LabVIEW sends to the notifier before
it calls this function.

If TRUE and the notifier contains a message before you call this function, this function waits until
the notifier receives another message. If FALSE (default) and the notifier contains a message
before you call this function, this function continues to execute.
• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for the notifier to
receive a message.

The default is –1, which indicates never to time out.

If the function waits timeout in ms and the notifier does not receive a message, timed out? is
TRUE.

• error in (no error) —

1944 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• notifiers out —

notifiers out returns an array of the notifier references from which messages were received.

• notifications —

notifications is an array of the last messages the notifiers receive.

This data type changes to match the subtype of notifiers, unless the subtype is an array. If the
subtype is an array, the data type becomes a cluster of arrays.
• timed out? —

timed out? is TRUE if the notifier does not receive a message before the function times out or if
an error occurs.

• error out —

error out contains error information. This output provides standard error out functionality.

Each unique instance of this function remembers the time stamp of the most recent
message for each individual notifier.

Maintaining notifier history prevents dropped messages and other problems when you
use this function repeatedly with different notifiers. When one of the notifiers in the
array receives a message, this function continues to execute. Use the Send Notification
function to send the message. If a notifier reference becomes invalid, such as when
another function closes it, this function stops waiting and returns error code 1122. If
the notifier does not contain a message, this function waits until a notifier within the
array receives a message.

Maintaining notifier history also causes this function to run slower than the Wait on
Notification from Multiple function, which does not maintain notifier history and might
experience deadlock when you use it repeatedly with different notifiers.

Use the Wait on Notification with Notifier History function for a single notifier
reference.

© National Instruments 1945

 Functions

If ignore previous is FALSE, each instance of the Wait on Notification from Multiple
with Notifier History function waits if it has not received notification. If one or more of
the notifiers have messages newer than the time stamp most recently received by this
function, the function returns all messages. Otherwise, the function waits.

When ignore previous is TRUE, this function always waits for a new message, even if
the message currently in the notifier is one it has never seen before.

This function does not remove the message from the notifier. Although a specific
instance of the function returns a message only once, other instances of the function
or the Wait on Notification function repeat the message until you call the Send
Notification function with a new message.

Queue Operations

Use the Queue Operations functions to create a queue for communicating data
between sections of a block diagram or from another VI.

Unlike the Notifier Operations functions, the Queue Operations functions buffer data.

Palette
Description
Object
Obtain
Queue Returns a reference to a queue.
Function
Enqueue
Element Adds an element to the back of a queue.
Function
Preview
Queue Returns the element at the front of the queue without removing the element from the
Element queue.
Function
Get Returns information about the current state of a queue, such as the number of elements
Queue currently in the queue.

1946 ni.com
 Functions

Palette
Description
Object
Status
Function
Release
Queue Releases a reference to a queue.
Function
Adds an element to a queue. If no space is available in the queue, this function removes
Lossy
an element from the front of the queue and discards the element to make space. Unlike
Enqueue
the Enqueue Element function, this function does not wait for room in the queue to
Element
become available. Use the Obtain Queue function to set the maximum size of the
Function
queue.
Enqueue
Element
At
Adds an element to the front of a queue.
Opposite
End
Function
Dequeue
Element Removes an element from the front of a queue and returns the element.
Function
Flush
Queue Removes all elements from a queue and returns the elements as an array.
Function

Obtain Queue Function

Returns a reference to a queue.

Use this reference when calling other Queue Operations functions.

© National Instruments 1947

 Functions

Inputs/Outputs
• max queue size (-1, unlimited) —

max queue size is the maximum number of elements you want the queue to hold.

The default is –1, specifying that the queue can hold an unlimited number of elements.

If a queue reaches max queue size, the Enqueue Element or Enqueue Element at Opposite End
functions wait until the Dequeue Element or Flush Queue functions remove elements from the
queue.

If a queue with the same name exists, LabVIEW ignores this input and uses the size from the
existing queue.

Note (Real-Time Module) max queue size preallocates the specified number of
elements in the queue of scalar data types when running on an RT target.

Note When not running on an RT target, max queue size only limits the number of
elements in the queue and does not preallocate the queue. To preallocate memory
for a queue, enqueue that number of elements and then flush the queue. The space
remains allocated for further use of the queue. Refer to the Details section for more
information on memory allocation for queues.

• name (unnamed) —

name contains the name of the queue that you want to obtain or create.

The default is an empty string to create an unnamed queue.

• element data type —

element data type is the type of data that you want the queue to contain.

You can wire any data type to this input.

• create if not found? (T) —

create if not found? specifies whether you want to create a new queue if one with the same
name as name does not exist.

If TRUE (default), the function creates a queue if one with the same name does not exist.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

1948 ni.com
 Functions

standard error in functionality.

• queue out —

queue out is a reference to the existing queue or the new queue created by this function.

• created new? —

created new? is TRUE if the function created a new queue.

• error out —

error out contains error information. This output provides standard error out functionality.

When you enqueue and dequeue resizable data types, such as paths, strings and
arrays, you do not affect the memory used by queues. Queues transfer data, but do not
generate copies of the data. Use the Lossy Enqueue Element function if you are
concerned that elements waiting to enter an already-full queue might cause jitter in a
deterministic loop.

Use named queues to pass data between two sections of a block diagram or between
two VIs in the same application instance. If you do not wire name, the function creates
a new, unnamed queue reference. If you wire name, the function searches for an
existing queue with the same name and returns a new reference to the existing queue.
If a queue with the same name does not already exist and create if not found? is TRUE,
the function creates a new, named queue reference.

If you use the Obtain Queue function to return a reference to a named queue inside a
loop, LabVIEW creates a new reference to the named queue each time the loop
iterates. If you use Obtain Queue in a tight loop, LabVIEW slowly increases how much
memory it uses because each new reference uses an additional four bytes. These bytes
are released automatically when the VI stops running. However, in a long-running
application it may appear as if LabVIEW is leaking memory since the memory usage
keeps increasing. To prevent this unintended memory allocation, use the Release
Queue function in the loop to release the queue reference for each iteration.

This function might return error codes 1, 2, 1094, 1100, 1491, or 1548.

© National Instruments 1949

 Functions

Note

You cannot use queues or named queues to communicate across application

instances. If you attempt to communicate with a named queue in another
application instance, LabVIEW does not return an error but you might not
receive the expected results.

If you obtain a queue reference in one application instance, you cannot use
that queue reference in another application instance. If you attempt to use a
queue reference in another application instance, LabVIEW returns error 1491.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Queue\Queue Overflow and

Underflow.vi

Enqueue Element Function

Adds an element to the back of a queue.

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• element —

element is the element you want to add to the back of the queue.

This data type changes to match the subtype of queue.

1950 ni.com
 Functions

• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for available space in
the queue if the queue is full.

The default is –1, indicating never to time out.

If the function waits timeout in ms and the queue remains full, timed out? is TRUE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• queue out —

queue out returns the reference to the queue unchanged.

• timed out? —

timed out? returns TRUE if space in the queue did not become available before the function
times out. timed out? also returns TRUE if this function encounters an error.

• error out —

error out contains error information. This output provides standard error out functionality.

If the queue is full, the function waits timeout in ms before timing out. If space
becomes available in the queue during the wait, the function inserts the element and
timed out? is FALSE. If queue becomes invalid such as when you release the queue
reference, the function stops waiting and returns error code 1122. Use the Obtain
Queue function to set the maximum size of the queue.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Queue\Queue Overflow and

Underflow.vi

© National Instruments 1951

 Functions

Preview Queue Element Function

Returns the element at the front of the queue without removing the element from the
queue.

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for an element to
become available in the queue if the queue is empty.

The default is –1, indicating never to time out.

If the function waits timeout in ms and the queue remains empty, timed out? is TRUE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• queue out —

queue out returns the reference to the queue unchanged.

• element —

element is the element at the front of the queue.

This data type changes to match the subtype of queue.

• timed out? —

timed out? returns TRUE if an element did not become available in the queue before the

1952 ni.com
 Functions

function timed out. timed out? also returns TRUE if this function encounters an error.

• error out —

error out contains error information. This output provides standard error out functionality.

Use the Dequeue Element function to return the element at the front of the queue and
remove it from the queue. If the queue is empty, the function waits timeout in ms
before timing out. If an element becomes available in the queue during the wait, the
function returns the element and timed out? is FALSE. If queue becomes invalid (for
example, the queue reference is released), the function stops waiting and returns error
code 1122.

Get Queue Status Function

Returns information about the current state of a queue, such as the number of
elements currently in the queue.

You also can use this function to verify that queue is a valid queue refnum. If queue is
not a valid queue refnum, the function returns error code 1.

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• return elements? (F) —

© National Instruments 1953

 Functions

return elements? indicates whether to return the elements in the queue.

If FALSE (default), the function does not return the elements in the queue.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• max queue size —

max queue size is the maximum number of elements the queue can contain. If max queue size
is –1, the queue can contain any number of elements.

Note max queue size only limits the number of elements in the queue. It does not
preallocate that number of elements in the queue.

• queue name —

queue name is the name of the queue.

• queue out —

queue out returns the reference to the queue unchanged.

• # pending remove —

# pending remove is the number of Dequeue Element or Preview Queue Element functions
currently waiting to remove an element from the queue.

Refer to the Dequeue Element and Preview Queue Element functions for more information.
• # pending insert —

# pending insert is the number of functions currently waiting to insert an element in the queue.

Use the Enqueue Element or Enqueue Element at Opposite End functions to insert an element in
the queue.

If the max queue size is –1, # pending insert is 0.

• error out —

error out contains error information. This output provides standard error out functionality.

• # elements in queue —

1954 ni.com
 Functions

# elements in queue returns the current number of elements in the queue.

• elements —

elements returns all the elements currently in the queue, but does not remove them from the
queue.

If return elements? is FALSE, this array is empty. This data type changes to match the subtype of
queue.

Release Queue Function

Releases a reference to a queue.

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• force destroy? (F) —

force destroy? indicates whether to destroy the queue.

If FALSE (default) and you want to destroy the queue, either call the Release Queue function a
number of times equal to the number of times you obtained a reference to the queue or stop all
VIs using the queue reference. If TRUE, the function destroys the queue and you do not have to
call the function multiple times or stop all VIs using the queue reference. Destroying the queue
invalidates all references to the queue.
• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• queue name —

© National Instruments 1955

 Functions

queue name is the name of the queue.

• remaining elements —

remaining elements is the array of elements that were in the queue before the function released
the queue.

The first element in the array is the element from the front of the queue and the last element in
the array is the element from the back of the queue.

This data type changes to match the subtype of queue.

• error out —

error out contains error information. This output provides standard error out functionality.

You can use the Obtain Queue function to obtain a reference to the same queue with
the same name multiple times. To destroy a queue, call the Release Queue function a
number of times equal to the number of times you obtained a reference to the queue
or stop all VIs using the queue reference.

If force destroy? is TRUE, this function releases all references to the queue and
destroys the queue.

Any Enqueue Element, Enqueue Element at Opposite End, Preview Queue Element,
and Dequeue Element functions waiting on the queue time out and return error code
1122.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Queue\Queue Overflow and

Underflow.vi

Lossy Enqueue Element Function

Adds an element to a queue. If no space is available in the queue, this function

removes an element from the front of the queue and discards the element to make

1956 ni.com
 Functions

space. Unlike the Enqueue Element function, this function does not wait for room in
the queue to become available. Use the Obtain Queue function to set the maximum
size of the queue.

Inputs/Outputs
• queue —

queue is a reference to a queue. Use the Obtain Queue function to obtain a queue reference.

• element —

element is the element you want to add to the back of the queue. This data type changes to
match the subtype of queue.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• queue out —

queue out is a reference to the existing queue.

• overflow element —

overflow element is the element LabVIEW removed from the front of the queue if the queue was
full.

• overflow? —

overflow? returns TRUE if the queue was full and LabVIEW removed an element to create space.
overflow? returns FALSE if the queue accepted the element and did not remove an element to
make space.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1957

 Functions

Enqueue Element At Opposite End Function

Adds an element to the front of a queue.

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• element —

element is the element you want to add to the front of the queue.

This data type changes to match the subtype of queue.

• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for available space in
the queue if the queue is full.

The default is –1, indicating never to time out.

If the function waits timeout in ms and the queue remains full, timed out? is TRUE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• queue out —

queue out returns the reference to the queue unchanged.

• timed out? —

timed out? returns TRUE if space in the queue did not become available before the function
times out. timed out? also returns TRUE if this function encounters an error.

1958 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

This function is similar to the Enqueue Element function. If the queue is full, the
function waits timeout in ms before continuing. If queue becomes invalid (for
example, the queue reference is released), the function stops waiting and returns error
code 1122.

Queues typically use a first-in-first-out flow of data. In rare situations, you might want
to interrupt this normal flow of data by adding an element to the front of the queue.
After you add an element to the front of a queue, the next Dequeue Element function
you call removes the element you added to the front. For example, you could use this
function if you want to use the queue as a stack structure or add high-priority
elements to the front of the queue.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Queue\Queue Stack Maze

Solver.vi

Dequeue Element Function

Removes an element from the front of a queue and returns the element.

If the queue is empty, the function waits timeout in ms before timing out. If an
element becomes available in the queue during the wait, the function removes and
returns the element and timed out? is FALSE. If queue becomes invalid (for example,
the queue reference is released), the function stops waiting and returns error code
1122.

© National Instruments 1959

 Functions

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• timeout in ms (-1) —

timeout in ms specifies the time, in milliseconds, that the function waits for an element to
become available in the queue if the queue is empty.

The default is –1, indicating never to time out.

If the function waits timeout in ms and the queue remains empty, timed out? is TRUE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• queue out —

queue out returns the reference to the queue unchanged.

• element —

element is the element at the front of the queue.

This data type changes to match the subtype of queue.

• timed out? —

timed out? returns TRUE if an element did not become available in the queue before the
function timed out. timed out? also returns TRUE if this function encounters an error.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

1960 ni.com
 Functions

• labview\examples\Synchronization\Queue\Queue Overflow and

Underflow.vi

Flush Queue Function

Removes all elements from a queue and returns the elements as an array.

This function does not release the queue reference. Use the Release Queue function to
release the reference.

Inputs/Outputs
• queue —

queue is a reference to a queue.

Use the Obtain Queue function to obtain a queue reference.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• queue out —

queue out returns the reference to the queue unchanged.

• remaining elements —

remaining elements is an array of elements removed from the queue.

The first element in the array is the element from the front of the queue and the last element in
the array is the element from the back of the queue.

This data type changes to match the subtype of queue.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 1961

 Functions

Semaphore

Use the Semaphore VIs to limit the number of tasks that can simultaneously operate
on a shared (protected) resource. A protected resource or critical section of code might
include writing to global variables or communicating with external instruments.

You can use the Semaphore VIs to synchronize two or more separate, parallel tasks so
that only one task at a time executes a critical section of code protected by a common
semaphore. In particular, use these VIs when you want certain VIs or parts of a block
diagram to wait until another VI or part of a block diagram is finished with the
execution of a critical section.

Palette Object Description

Obtain
Obtains a reference to an existing semaphore or creates a new semaphore and
Semaphore
returns a reference to that semaphore.
Reference

Acquire
Acquires access to a semaphore.
Semaphore

Release Releases access to a semaphore. If the Acquire Semaphore VI is waiting for the
Semaphore semaphore this VI releases, it stops waiting and continues execution.

Release
Semaphore Releases a reference to a semaphore.
Reference

Get Semaphore
Returns current status information of a semaphore.
Status

Not A
Returns TRUE if semaphore is not a valid semaphore refnum.
Semaphore

1962 ni.com
 Functions

Obtain Semaphore Reference

Obtains a reference to an existing semaphore or creates a new semaphore and returns

a reference to that semaphore.

Use this VI in conjunction with the other Semaphore VIs to implement a semaphore in
LabVIEW.

Inputs/Outputs
• name (unnamed) —

name contains the name of the semaphore you want to look up or create.

The default is an empty string to create an unnamed semaphore. If you wire name, LabVIEW
searches for an existing semaphore with the same name and returns a unique reference to the
existing semaphore. If a semaphore with the same name does not already exist and create if not
found is TRUE, LabVIEW creates a new, named semaphore and returns a unique reference to that
semaphore.

• size (1) —

size specifies how many tasks can acquire the semaphore at the same time. If a named
semaphore already exists, wiring a value to this parameter does not resize the semaphore.

size must be greater than or equal to 1. The default is 1.

• create if not found (T) —

create if not found specifies whether you want to create a new semaphore if one with that name
does not exist.

The default is TRUE, which specifies that LabVIEW creates a semaphore if the semaphore does
not exist. If create if not found is FALSE and LabVIEW cannot find a semaphore with the name
you specify, LabVIEW returns error code 1534.

• error in (no error) —

© National Instruments 1963

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• semaphore —

semaphore is a reference to an existing or newly created semaphore.

If you use this VI to obtain multiple references to the same named semaphore, each reference
number is unique.

• created new —

created new is TRUE if the VI created a new semaphore.

• error out —

error out contains error information. This output provides standard error out functionality.

You cannot use semaphores to communicate between LabVIEW application instances.

If you obtain a reference to a semaphore in one application instance, you cannot use
that semaphore reference in another application instance.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Semaphore\Simple
Semaphore.vi

Acquire Semaphore

Acquires access to a semaphore.

Use this VI in conjunction with the other Semaphore VIs to implement a semaphore in
LabVIEW.

1964 ni.com
 Functions

Inputs/Outputs
• semaphore —

semaphore is a reference to a semaphore.

• ms timeout (-1) —

ms timeout specifies how many milliseconds the function should wait for the semaphore to
become available.

The default is -1, indicating never to time out.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• semaphore out —

semaphore out has the same value as semaphore.

• timed out —

timed out is TRUE if the semaphore did not become available before the function timed out or if
an error occurred.

• error out —

error out contains error information. This output provides standard error out functionality.

If the semaphore is already acquired by the maximum number of tasks, the VI waits ms
timeout milliseconds before timing out. If the semaphore becomes available during
the wait, timed out is FALSE. If the semaphore does not become available or
semaphore is not valid, timed out is TRUE. The count on a semaphore is incremented
each time Acquire Semaphore executes, even if the task acquiring the semaphore has
already acquired it once.

© National Instruments 1965

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Semaphore\Simple
Semaphore.vi

Release Semaphore

Releases access to a semaphore. If the Acquire Semaphore VI is waiting for the

semaphore this VI releases, it stops waiting and continues execution.

Use this VI in conjunction with the other Semaphore VIs to implement a semaphore in
LabVIEW.

Inputs/Outputs
• semaphore —

semaphore is a reference to a semaphore.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• semaphore out —

semaphore out has the same value as semaphore.

• error out —

error out contains error information. This output provides standard error out functionality.

1966 ni.com
 Functions

If the semaphore is currently unacquired, this VI returns error code 1111.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Semaphore\Simple
Semaphore.vi

Release Semaphore Reference

Releases a reference to a semaphore.

Use this VI in conjunction with the other Semaphore VIs to implement a semaphore in
LabVIEW.

Inputs/Outputs
• semaphore —

semaphore is a reference to a semaphore.

• force destroy? (F) —

force destroy? specifies whether to destroy the semaphore.

If FALSE (default), LabVIEW destroys the semaphore only if no other references to the semaphore
exist. If TRUE, LabVIEW releases all references to the semaphore and destroys the semaphore.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• semaphore name —

© National Instruments 1967

 Functions

semaphore name is the name of the semaphore.

• error out —

error out contains error information. This output provides standard error out functionality.

All Acquire Semaphore VIs that are currently waiting on this reference to the
semaphore time out immediately and return an error. This does not affect any Acquire
Semaphore VIs that are waiting on a different reference to the same semaphore.
However, if force destroy? is TRUE, all Acquire Semaphore VIs, including those that are
waiting on a different reference to the semaphore, time out immediately and return an
error.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Semaphore\Simple
Semaphore.vi

Get Semaphore Status

Returns current status information of a semaphore.

Use this VI in conjunction with the other Semaphore VIs to implement a semaphore in
LabVIEW.

Inputs/Outputs
• semaphore —

1968 ni.com
 Functions

semaphore is a reference to a semaphore.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• name —

name contains the name of the semaphore.

• semaphore out —

semaphore out has the same value as semaphore.

• # available —

# available contains the number of tasks that can acquire the semaphore at the current time.
This number is always less than or equal to size.

• # waiting —

# waiting is the number of Acquire Semaphore functions currently waiting to acquire the
semaphore.

• error out —

error out contains error information. This output provides standard error out functionality.

• size —

size contains the maximum number of tasks that can acquire the semaphore at a time.

Not A Semaphore

Returns TRUE if semaphore is not a valid semaphore refnum.

Use this VI in conjunction with the other Semaphore VIs to implement a semaphore in
LabVIEW.

© National Instruments 1969

 Functions

Inputs/Outputs
• semaphore —

semaphore is a reference to a semaphore.

• not a semaphore —

not a semaphore is TRUE if semaphore is not a valid semaphore reference.

Rendezvous

Use the Rendezvous VIs to synchronize two or more separate, parallel tasks at specific
points of execution. Each task that reaches the rendezvous waits until the specified
number of tasks are waiting, at which point all tasks proceed with execution.

Palette Object Description

Looks up an existing rendezvous or creates a new rendezvous and returns a

Create Rendezvous
refnum.

Wait at Rendezvous Waits until a sufficient number of tasks have arrived at the rendezvous.

Resize Rendezvous Changes the size of rendezvous by size change and returns new size.

Destroy Rendezvous Destroys the specified rendezvous.

Get Rendezvous
Returns current status information of a rendezvous.
Status

Not A Rendezvous Returns TRUE if rendezvous is not a valid rendezvous refnum.

1970 ni.com
 Functions

Create Rendezvous

Looks up an existing rendezvous or creates a new rendezvous and returns a refnum.

You can use this refnum when calling other Rendezvous VIs.

Inputs/Outputs
• name (unnamed) —

name contains the name of the rendezvous that you are looking up or creating.

The default is an empty string to create an unnamed rendezvous. LabVIEW does not
automatically release named rendezvous.

Note A named rendezvous exists only as long as the top-level VI that first created the
named rendezvous continues running. For example, if Application.vi has a
subVI Subtask.vi, any named rendezvous created by Subtask.vi is cleaned up
when Application.vi stops executing. You can use the same named rendezvous
in any VI—even those not in the hierarchy of Application.vi—but the
rendezvous ceases to exist when the Application.vi hierarchy shuts down.

• size (2) —

size specifies how many tasks initially meet at the rendezvous to continue execution.

The default is 2. If a named rendezvous already exists, wiring a value to size does not resize the
rendezvous. Use the Resize Rendezvous to resize a named rendezvous.

• return existing (F) —

return existing (F) specifies whether the rendezvous must already exist for this function to
succeed.

The default is FALSE, specifying that a rendezvous should be created if it does not exist. If return
existing (F) is TRUE and a rendezvous with that name does not exist, the function returns an
error.

© National Instruments 1971

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• rendezvous —

rendezvous is a reference to an existing or newly created rendezvous.

• created new —

created new is TRUE if the VI created a new rendezvous.

• error out —

error out contains error information. This output provides standard error out functionality.

If name is specified, the VI first searches for an existing rendezvous with the same
name and returns its refnum if it exists. If a named rendezvous with the same name
does not already exist and return existing is FALSE, the VI creates a new rendezvous
and returns its refnum. created new is TRUE if the VI creates a new rendezvous.

Note You cannot use a rendezvous to communicate between LabVIEW

application instance. If you create a rendezvous reference in one application
instance, you cannot use that rendezvous reference in another application
instance.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Rendezvous\Simple
Rendezvous.vi

Wait at Rendezvous

Waits until a sufficient number of tasks have arrived at the rendezvous.

1972 ni.com
 Functions

Inputs/Outputs
• rendezvous —

rendezvous is a reference associated with a rendezvous.

• ms timeout (-1) —

ms timeout specifies how many milliseconds the function should wait for other tasks to arrive at
the rendezvous.

The default is –1, indicating never to time out.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• rendezvous out —

rendezvous out has the same value as rendezvous.

• timed out —

timed out is TRUE if not enough tasks arrived before the function timed out or if an error
occurred.

• error out —

error out contains error information. This output provides standard error out functionality.

If the number of tasks, including the new one, waiting at rendezvous is less than the
rendezvous size, the VI waits ms timeout milliseconds before timing out. If enough
tasks arrive at the rendezvous during the wait, timed out is FALSE. If enough tasks do
not arrive or rendezvous is not valid, timed out is TRUE.

Resize Rendezvous

Changes the size of rendezvous by size change and returns new size.

© National Instruments 1973

 Functions

Inputs/Outputs
• rendezvous —

rendezvous is a reference associated with a rendezvous.

• size change (0) —

size change specifies how many more tasks want to meet at the rendezvous.

A negative size decreases the number of tasks. The default is 0 for no change in size.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• rendezvous out —

rendezvous out has the same value as rendezvous.

• new size —

new size is the new number of tasks meeting at the rendezvous.

• error out —

error out contains error information. This output provides standard error out functionality.

Destroy Rendezvous

Destroys the specified rendezvous.

All Wait at Rendezvous VIs that are currently waiting on this rendezvous time out
immediately and return an error.

1974 ni.com
 Functions

Inputs/Outputs
• rendezvous —

rendezvous is a reference associated with a rendezvous.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• rendezvous name —

rendezvous name is the name of rendezvous.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Rendezvous\Simple
Rendezvous.vi

Get Rendezvous Status

Returns current status information of a rendezvous.

© National Instruments 1975

 Functions

Inputs/Outputs
• rendezvous —

rendezvous is a reference associated with a rendezvous.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• name —

name contains the name of the rendezvous.

• rendezvous out —

rendezvous out has the same value as rendezvous.

• # waiting —

# waiting is the number of Wait at Rendezvous functions currently waiting at the rendezvous.

• size —

size is the number of tasks meeting at the rendezvous.

• error out —

error out contains error information. This output provides standard error out functionality.

Not A Rendezvous

Returns TRUE if rendezvous is not a valid rendezvous refnum.

Inputs/Outputs
• rendezvous —

1976 ni.com
 Functions

rendezvous is a reference associated with a rendezvous.

• not a rendezvous —

not a rendezvous is TRUE if rendezvous is not a valid rendezvous reference.

Occurrences

Use the Occurrences functions to control separate, synchronous activities.

In particular, use these functions when you want one VI or part of a block diagram to
wait until another VI or part of a block diagram finishes a task without forcing LabVIEW
to poll.

You can perform the same task using global variables, with one loop polling the global
variable until its value changes. However, global variables use more overhead because
the loop that waits uses execution time. With occurrences, the second loop becomes
idle and does not use processor time. When the first loop sets the occurrence, LabVIEW
activates the second loop and any other block diagrams that wait for the specified
occurrence.

Palette Object Description

Generate Occurrence Generates an occurrence that you can pass to the Wait on Occurrence and
Function Set Occurrence functions.
Wait on Occurrence
Waits for the Set Occurrence function to set the given occurrence.
Function
Set Occurrence Sets the specified occurrence. All nodes that are waiting for this occurrence
Function stop waiting.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 1977

 Functions

• labview\examples\Synchronization\Occurrence\Simple
Occurrence.vi

Generate Occurrence Function

Generates an occurrence that you can pass to the Wait on Occurrence and Set
Occurrence functions.

Note National Instruments encourages you to use the Notifier Operations

functions in place of occurrences for most operations.

Inputs/Outputs
• occurrence —

occurrence is the occurrence refnum that links Wait on Occurrence and Set Occurrence.

Ordinarily, only one Generate Occurrence function is wired to any set of Wait on
Occurrence and Set Occurrence functions. You can wire a Generate Occurrence
function to any number of Wait on Occurrence and Set Occurrence functions. You do
not have to have the same number of Wait on Occurrence and Set Occurrence
functions.

Unlike other Synchronization VIs, each Generate Occurrence function on a block

diagram represents a single, unique occurrence. In this way, the Generate Occurrence
function is similar to a constant. When a VI is running, every time a Generate
Occurrence function executes, the function produces the same value. For example, if
you place a Generate Occurrence function inside of a loop, the value produced by the
Generate Occurrence function is the same for every iteration of the loop. If you place a
Generate Occurrence function on the block diagram of a reentrant VI, the Generate
Occurrence function produces a different value for each caller.

1978 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Occurrence\Simple
Occurrence.vi

Wait on Occurrence Function

Waits for the Set Occurrence function to set the given occurrence.

Note National Instruments encourages you to use the Notifier Operations

functions in place of occurrences for most operations.

Inputs/Outputs
• ms timeout (-1) —

ms timeout is the specified amount of time, in milliseconds, for occurrence to occur.

If occurrence does not occur within the specified ms timeout, the function returns a value of
TRUE. If ms timeout is –1 (default), the function does not time out unless the occurrence wired
to this function is invalid. If occurrence is invalid, the function immediately returns TRUE for
timed out, even if ms timeout is equal to –1 (default).

• occurrence —

occurrence is the occurrence refnum that links Wait on Occurrence and Set Occurrence.

• ignore previous (T) —

If ignore previous is TRUE (default) and another node has set the occurrence before this
function began executing, the function ignores the previous occurrence and waits for another
one.

© National Instruments 1979

 Functions

When ignore previous is FALSE, the function checks whether another node previously set an
occurrence. If so, the function executes. However, the Wait on Occurrence function only
processes one occurrence at a time and does not hold multiple previous occurrences in memory.

• timed out —

timed out is TRUE if occurrence does not occur within the specified ms timeout or if occurrence
is invalid, even if ms timeout is equal to –1.

If ms timeout is –1 and occurrence is valid, timed out is FALSE.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Occurrence\Simple
Occurrence.vi

Set Occurrence Function

Sets the specified occurrence. All nodes that are waiting for this occurrence stop
waiting.

Note National Instruments encourages you to use the Notifier Operations

functions in place of occurrences for most operations.

Inputs/Outputs
• occurrence —

occurrence is the occurrence refnum that links Wait on Occurrence and Set Occurrence.

1980 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Synchronization\Occurrence\Simple
Occurrence.vi

First Call? Function

Indicates that a subVI or section of a block diagram is running for the first time. The
First Call? function returns TRUE only the first time you call it after you click the Run
button.

You can place the First Call? function in multiple locations within a VI. The function
returns TRUE the first time the section of the block diagram in which it is placed runs.

Inputs/Outputs
• First Call?: T/F —

First Call? is TRUE if the subVI is running for the first time since you ran the entire VI.

This function is useful if you want to run a subVI or a section of a block diagram within
a loop or Case structure only once when the VI runs.

First Call? returns TRUE the first time the VI runs after the first top-level caller starts
running, such as when the Run button is clicked or the Run VI method executes. If a
second top-level caller calls the VI while the first top-level caller is still running, First
Call? does not return TRUE a second time. After all the top-level callers become idle
and a top-level caller starts again, First Call? returns TRUE the first time the VI runs
after the idle state. Reentrant VIs have an instance per data space. Therefore, a shared
reentrant VI returns TRUE for each data space instance the first time its top-level caller
calls it.

© National Instruments 1981

 Functions

Synchronize Data Flow

Passes through the values of the input wires after the upstream code executes.

Use this VI to synchronize multiple parallel code paths at a single point of data flow to
ensure a certain execution order.

Inputs/Outputs
• input 1 —

input 1 specifies the value of the first wire.

This input accepts any data type. The default data type is a variant.

• input 2 —

input 2 specifies the value of the second wire.

This input accepts any data type. The default data type is a variant.

• input 3 —

input 3 specifies the value of the third wire.

This input accepts any data type. The default data type is a variant.

• input 4 —

input 4 specifies the value of the fourth wire.

This input accepts any data type. The default data type is a variant.

• output 1 —

output 1 returns the value of input 1.

• output 2 —

1982 ni.com
 Functions

output 2 returns the value of input 2.

• output 3 —

output 3 returns the value of input 3.

• output 4 —

output 4 returns the value of input 4.

Graphics & Sound

Use the Graphics & Sound VIs to create custom displays, import and export data from
graphics files, and play sounds.

Palette
Description
Object

3D Graph
Use the 3D Graph Properties VIs to create 3D data displays.
Properties

Picture
Use the Picture Plots VIs to create graphical representations of data.
Plots

Use the Picture Functions VIs to create visual representations of data. Many of these
Picture picture VIs use clusters to define points and rectangles. The VIs related to drawing text
Functions use clusters and enumerations to describe the font choice and the positioning of the
text.

Graphics Use the Graphics Formats VIs to retrieve or store image data in BMP, JPEG, or PNG
Formats image files.

© National Instruments 1983

 Functions

Palette
Description
Object

Beep Causes the system to issue an audible tone. (Windows Vista 64-bit) This VI might not
(Windows) work correctly if use system alert? is FALSE.

Sound Use the Sound VIs to play sounds.

3D Picture Use the 3D Picture Control VIs to display graphical representations of objects in 3D
Control scenes.

3D Graph Properties

Use the 3D Graph Properties VIs to create 3D data displays.

Note The 3D Graph Properties VIs are available on Windows only, because
the ActiveX 3D graph is an ActiveX control, which is available only on
Windows.

Palette
Description
Object

Plots a simple surface from z matrix. The x and y vectors cause the surface to shift in
3D Surface relation to the x and y planes. This VI accepts one 2D array and the two optional 1D
arrays.

3D
Plots a surface in terms of x, y, and z surfaces. The VI has three 2D array or matrix inputs
Parametric
that specify each of the x, y, and z planes.
Surface

1984 ni.com
 Functions

Palette
Description
Object

Describes a line in terms of x, y, and z points. This VI has three 1D array or vector inputs
3D Curve
that specify each point in the plot.

Basic Adjusts various properties of the plot, including the transparency, plot style, and
Properties coordinate system.

Axes
Adjusts the properties of the x-, y-, and z-axes, including scaling and inverting.
Properties

Grid
Shows or hides the xy, xz, yz grids.
Properties

Projection
Adjusts the types of projections associated with the plot.
Properties

Convert
Converts LabVIEW colors to or from colors used by ActiveX.
OLE Color

Set Plots Sets the number of plots that are available for a 3D graph control.

3D Surface

Plots a simple surface from z matrix. The x and y vectors cause the surface to shift in
relation to the x and y planes. This VI accepts one 2D array and the two optional 1D
arrays.

© National Instruments 1985

 Functions

Inputs/Outputs
• 3D graph —

3D graph accepts the reference to the 3D control.

• x vector —

x vector is a 1D array that describes the surface from z matrix in relation to the x plane.

• y vector —

y vector is a 1D array that describes the surface from the z matrix in relation to the y plane.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array of data that determines the surface in relation to the z plane.

The x and y vectors shift or skew the set of data in the z matrix.

• plot number (1) —

plot number is the index into the list of plots from the properties of the 3D control.

Add new plots by right-clicking the control and adjusting the properties. The default is the first
plot from the list.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

x vector and y vector correspond to the two indexes for the z matrix 2D array. If the
number of elements in x vector does not match the width of z matrix in the first
dimension, and the number of elements in y vector does not match the width of z
matrix in the second dimension, both x vector and y vector are ignored.

1986 ni.com
 Functions

The values of x vector and y vector specify where the corresponding point in the z
matrix should be located. The default values for x vector and y vector are 0, 1, 2, 3, and
so on. The first point in z matrix (index 0,0) is located at (x vector[0], y vector[0]), or
(0,0). If you change x vector to –1, 1, 2, 3, and so on, the first point in z matrix moves to
(–1,0).

3D Parametric Surface

Plots a surface in terms of x, y, and z surfaces. The VI has three 2D array or matrix
inputs that specify each of the x, y, and z planes.

Inputs/Outputs
• 3D graph —

3D graph accepts the reference to the 3D control.

• x matrix —

x matrix is a 2D array of data that determines the surface in relation to the x plane.

• y matrix —

y matrix is a 2D array of data that determines the surface in relation to the y plane.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array of data that determines the surface in relation to the z plane.

The x and y vectors shift or skew the set of data in the z matrix.

© National Instruments 1987

 Functions

• plot number (1) —

plot number is the index into the list of plots from the properties of the 3D control.

Add new plots by right-clicking the control and adjusting the properties. The default is the first
plot from the list.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

3D Curve

Describes a line in terms of x, y, and z points. This VI has three 1D array or vector inputs
that specify each point in the plot.

Inputs/Outputs
• 3D graph —

3D graph accepts the reference to the 3D control.

• x vector —

x vector is a 1D array of data that contains the x coordinates of the curve.

• y vector —

y vector is a 1D array of data that contains the y coordinates of the curve.

• error in (no error) —

1988 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z vector —

z vector is a 1D array of data that contains the z coordinates of the line or curve.

The x and y vectors shift or skew the set of data in the z vector.

• plot number (1) —

plot number is the index into the list of plots from the properties of the 3D control.

Add new plots by right-clicking the control and adjusting the properties. The default is the first
plot from the list.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D (ActiveX)\3D Curve Graph
(ActiveX).vi

Basic Properties

Adjusts various properties of the plot, including the transparency, plot style, and
coordinate system.

© National Instruments 1989

 Functions

Inputs/Outputs
• 3D graph —

3D graph accepts the reference to the 3D control.

• plot style —

plot style changes the way the data is plotted. The default is a surface plot.

• fast draw —

fast draw determines if the surface is redrawn while it is rotated and zoomed or if it is displayed
as points of data.

• transparency —

transparency is a value from 0 to 100 that changes the transparency of the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• coordinate system —

coordinate system can be cwCartesian, cwCylindrical, or cwSpherical.

The default is cwCartesian.

• plot number (1) —

plot number is the index into the list of plots from the properties of the 3D control.

Add new plots by right-clicking the control and adjusting the properties. The default is the first
plot from the list.

• 3D graph out —

1990 ni.com
 Functions

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Axes Properties

Adjusts the properties of the x-, y-, and z-axes, including scaling and inverting.

Inputs/Outputs
• invert x —

invert x reverses the plot along the x plane.

• invert y —

invert y reverses the plot along the y plane.

• invert z —

invert z reverses the plot along the z plane.

• 3D graph —

3D graph accepts the reference to the 3D control.

• auto scale x —

auto scale x enables autoscaling for the x plane.

• auto scale y —

© National Instruments 1991

 Functions

auto scale y enables autoscaling for the y plane.

• auto scale z —

auto scale z enables autoscaling for the z plane.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• plot number (1) —

plot number is the index into the list of plots from the properties of the 3D control.

Add new plots by right-clicking the control and adjusting the properties. The default is the first
plot from the list.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Grid Properties

Shows or hides the xy, xz, yz grids.

Inputs/Outputs
• grid smoothing —

1992 ni.com
 Functions

grid smoothing allows the grids to be drawn with smooth lines.

• 3D graph —

3D graph accepts the reference to the 3D control.

• xy grid —

xy grid shows the xy grid.

• xz grid —

xz grid shows the xz grid.

• yz grid —

yz grid shows the yz grid.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Projection Properties

Adjusts the types of projections associated with the plot.

The plot can be projected onto the xy plane, xz plane, or yz plane.

© National Instruments 1993

 Functions

Inputs/Outputs
• coordinate system —

coordinate system can be cwCartesian, cwCylindrical, or cwSpherical.

The default is cwCartesian.

• 3D graph —

3D graph accepts the reference to the 3D control.

• xy projection —

xy projection projects an image of the plot onto the xy plane.

• xz projection —

xz projection projects an image of the plot onto the xz plane.

• yz projection —

yz projection projects an image of the plot onto the yz plane.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• show projections only —

show projections only allows only the projections to be shown.

• plot number (1) —

plot number is the index into the list of plots from the properties of the 3D control.

1994 ni.com
 Functions

Add new plots by right-clicking the control and adjusting the properties. The default is the first
plot from the list.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Convert OLE Color

Converts LabVIEW colors to or from colors used by ActiveX.

You can use the property page for the 3D graph to set all of the colors. Color conversion
is necessary for use with ActiveX Property Nodes.

Inputs/Outputs
• color in —

color in is the color you want to convert.

• color out —

color out is the converted color.

Set Plots

Sets the number of plots that are available for a 3D graph control.

© National Instruments 1995

 Functions

Inputs/Outputs
• 3D graph —

3D graph accepts the reference to the 3D control.

• # of plots(1) —

# of plots sets the number of plots for a 3D control. It removes all of the plots that are currently
in the graph and adds the number of plots. The default is one plot for a control.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 3D graph out —

3D graph out passes the reference to the 3D control out so that you can use it with other VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Picture Plots

Use the Picture Plots VIs to create graphical representations of data.

Palette
Description
Object

Polar Plot
Takes a picture and polar data and appends a picture that represents a polar graph
with Point
of the data. This VI can represent polar data as points or lines between points.
Options

1996 ni.com
 Functions

Palette
Description
Object

Takes a picture and the data for a Smith plot and appends a picture that represents
Smith Plot
the Smith plot of the data.

Smith Multi Takes a picture and an array of Smith plots and appends a picture that represents
Plot the superimposed Smith plots of the data.

Normalize Takes data for a Smith plot and normalizes it, meaning that the data is scaled
Smith Plot relative to a known value.

Takes a picture and an array of points and appends a picture that represents an XY
Plot XY
graph of the data.

Takes a picture and an array of plots and appends a picture of an XY graph of the
Plot Multi-XY
data with the plots overlaid on the same graph.

Plot Takes uniformly distributed data and a picture and creates a new picture that
Waveform represents a waveform graph of the data.

Takes a picture and an array of plots and appends a picture that represents the
Radar Plot
radar plot of the data.

Draw Legend Takes a picture and adds a legend to the picture.

Calc Scale Takes a specification for a Cartesian style scale and calculates the coordinates and
Specs labels to use for the scale.

Draw Scale Draws a scale onto a picture.

© National Instruments 1997

 Functions

Palette
Description
Object

Uses pixel and data ranges to determine scale factors such that (a * data value) + b
Map Setup
is the pixel value that corresponds to that data value.

Map Value to Uses the domain value and the cluster returned by the Map Setup VI to determine a
Pixel pixel value corresponding to that domain value.

Map Pixel to Uses the pixel value and the cluster returned by the Map Setup VI to determine the
Value domain value corresponding to that pixel value.

Polar Plot with Point Options

Takes a picture and polar data and appends a picture that represents a polar graph of
the data. This VI can represent polar data as points or lines between points.

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

1998 ni.com
 Functions

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
1 Application Font

© National Instruments 1999

 Functions

(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the scale. The default is an empty picture.

• data array [mag, phase (deg)] —

data array is an array of points, where each point is a cluster containing a magnitude and a
phase in degrees that specifies the format and precision for the scale.

• magnitude —

magnitude is the straight line distance from the point to the center of the circle.

• phase —

phase is the angle (measured in degrees) between the positive x-axis and a straight line
from the center of the circle to the point.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• dimensions (w,h) —

dimensions specifies the top left point of the drawn bitmap.

• width —

2000 ni.com
 Functions

width specifies the horizontal coordinate that increases to the right.

• height —

height specifies the vertical coordinate that increases to the bottom.

• polar attributes —

polar attributes describes the format for the grid and scale of the polar plot and indicates how
the graph should handle negative magnitude data, whether to clip the data or to draw it.

• maximum —

maximum specifies the maximum value for the scale.

• minimum —

minimum specifies the minimum value for the scale.

• clip to min —

clip to min specifies whether to clip (TRUE) or draw (FALSE) negative magnitude data.

• log?(F) —

log? specifies if the scale is logarithmic.

• grid color —

grid color specifies the color of the grid.

The default in RGB is 102, 102, 102.

You can wire a color box constant to this input.

• plot color —

plot color specifies the color of the plot.

The default in RGB is 0, 255, 0.

© National Instruments 2001

 Functions

You can wire a color box constant to this input.

• fmt and prec —

fmt and prec specifies the numeric format and precision for the scale numbers.

• format —

format specifies the numeric format for the scale numbers.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• precision —

precision specifies the precision for the scale numbers. The default is 1.

• visible section —

visible section specifies which quadrant(s) of the polar plot you want to view.

0 Upper right quadrant

1 Lower right quadrant
2 Lower left quadrant
3 Upper left quadrant
4 Upper right and left quadrants
5 Lower right and left quadrants
6 Right upper and lower quadrants
7 Left upper and lower quadrants
8 All quadrants (default)

• Lines/Points —

2002 ni.com
 Functions

Lines/Points sets whether the VI represents the polar data as points or lines between points.

0 Lines
1 Points

• Size —

Size specifies the size, in pixels, of the lines or points this VI plots.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Simple

Polar Plot.vi

Smith Plot

Takes a picture and the data for a Smith plot and appends a picture that represents the
Smith plot of the data.

© National Instruments 2003

 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

2004 ni.com
 Functions

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the plot. The default is an empty picture.

• smith plot —

smith plot is an array of points, where each point is a cluster containing the r and x values that
make up the complex impedance, z, of r + jx.

• r—

r is the resistance component of the complex impedance.

• x—

x is the reactance component of the complex impedance.

• dimensions (w,h) —

dimensions specifies the top left point of the drawn bitmap.

• width —

width specifies the horizontal coordinate that increases to the right.

• height —

© National Instruments 2005

 Functions

height specifies the vertical coordinate that increases to the bottom.

• dimensions incl scales? (T) —

dimensions incl scales? indicates whether the dimensions input includes the scales, in addition
to the plot area.

If FALSE, the dimensions input describes the plot area, and the VI draws the scales outside of the
rectangle. If TRUE (default), the VI draws the scales inside of dimensions and insets the plot area
to make room for the text.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• smith plot section —

smith plot section describes the portion of the graph you want to display.

It contains four values that represent a rectangle superimposed over the Smith plot.

• x minimum —

x minimum is the smallest allowable value in the range of horizontal coordinates.

• x maximum —

x maximum is the largest allowable value in the range of horizontal coordinates.

• y minimum —

2006 ni.com
 Functions

y minimum is the smallest allowable value in the range of vertical coordinates.

• y maximum —

y maximum is the largest allowable value in the range of vertical coordinates.

• smith plot cosmetics —

smith plot cosmetics specifies the style to use in drawing the plot.

• Plot Style —

Plot Style is the style of plot to display.

The default is a plot of lines and points.

• Line Color —

Line Color is the color of the line.

The default in RGB is 0, 153, 255.

You can wire a color box constant to this input.

• Point Color —

Point Color is the color of the points.

The default in RGB is 0, 153, 255.

You can wire a color box constant to this input.

• smith grid cosmetics —

smith grid cosmetics describes the style to use for the grids.

• R color —

R color specifies the color of the resistance, r, circles for the grids.

© National Instruments 2007

 Functions

• R grids —

R grids specifies to draw the resistance, r, circles for the grids.

• X color —

X color specifies the color of the reactance, x, circles for the grids.

• X grids —

X grids specifies to draw the reactance, x, circles for the grids.

• Labels —

Labels specifies to draw labels in the plot corners when you zoom in on a section of the
plot.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Simple

Smith Plot.vi

Smith Multi Plot

Takes a picture and an array of Smith plots and appends a picture that represents the
superimposed Smith plots of the data.

2008 ni.com
 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

© National Instruments 2009

 Functions

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the plot. The default is an empty picture.

• rect —

rect contains the upper-left and lower-right coordinates that describe a rectangle bounding the
text.

The VI clips text to the coordinates of this rectangle. Horizontal coordinates increase to the right,
and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

2010 ni.com
 Functions

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• smith plot section —

smith plot section describes the portion of the graph you want to display.

It contains four values that represent a rectangle superimposed over the Smith plot.

• x minimum —

x minimum is the smallest allowable value in the range of horizontal coordinates.

• x maximum —

x maximum is the largest allowable value in the range of horizontal coordinates.

• y minimum —

y minimum is the smallest allowable value in the range of vertical coordinates.

• y maximum —

y maximum is the largest allowable value in the range of vertical coordinates.

• smith grid cosmetics —

smith grid cosmetics describes the style to use for the grids.

• R color —

R color specifies the color of the resistance, r, circles for the grids.

• R grids —

© National Instruments 2011

 Functions

R grids specifies to draw the resistance, r, circles for the grids.

• X color —

X color specifies the color of the reactance, x, circles for the grids.

• X grids —

X grids specifies to draw the reactance, x, circles for the grids.

• Labels —

Labels specifies to draw labels in the plot corners when you zoom in on a section of the
plot.

• smith multi plot —

smith multi plot is an array of clusters, where each cluster contains an array of points.

A point is represented by a cluster containing the r and x values that make up the complex
impedance r + jx.

• smith plot —

smith plot is an array of points, where each point is a cluster containing the r and x values
that make up the complex impedance, z, of r + jx.

• r—

r is the resistance component of the complex impedance.

• x—

x is the reactance component of the complex impedance.

• smith plot cosmetics —

smith plot cosmetics specifies the style to use in drawing the plot.

2012 ni.com
 Functions

• Plot Style —

Plot Style is the style of plot to display.

The default is a plot of lines and points.

• Line Color —

Line Color is the color of the line.

The default in RGB is 0, 153, 255.

You can wire a color box constant to this input.

• Point Color —

Point Color is the color of the points.

The default in RGB is 0, 153, 255.

You can wire a color box constant to this input.

• dimensions incl scales? (T) —

dimensions incl scales? indicates whether the rect input includes the scales, in addition to the
plot area.

If FALSE, the rect input describes the plot area, and the VI draws the scales outside of the
rectangle. If TRUE, the VI draws the scales inside of rect and insets the plot area to make room
for the text.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

© National Instruments 2013

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Smith

Multi Plot with Styles.vi

Normalize Smith Plot

Takes data for a Smith plot and normalizes it, meaning that the data is scaled relative
to a known value.

Inputs/Outputs
• Zo (50.0) —

Zo is the characteristic impedance of the system.

• points {r,x} —

points {r,x} is an array of points, where each point is a cluster containing the r and x values that
make up the complex impedance r + jx.

• r—

r is the resistance component of the complex impedance.

• x—

x is the reactance component of the complex impedance.

• points complex —

points complex is an array of complex numbers.

• normalized smith points {r,x} —

2014 ni.com
 Functions

normalized smith points {r,x} is an array of clusters of points containing the normalized data.
Each cluster contains an r and an x value.

• r—

r is the resistance component of the complex impedance.

• x—

x is the reactance component of the complex impedance.

You can wire an array of points to this VI, where each point is a cluster of an r and an x
value, or you can wire an array of complex data to this VI. The VI detects which data
input you wire and uses that input. If you wire both inputs, the VI normalizes the array
of points.

This VI normalizes the data with respect to a specified characteristic impedance, Zo, of
the system. Then it returns the resulting data as an array of clusters of points, where
each cluster contains an r and an x value. You can wire the normalized smith points
output directly to the Smith Plot VI.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Smith

Multi Plot with Styles.vi

Plot XY

Takes a picture and an array of points and appends a picture that represents an XY
graph of the data.

To create controls for the cluster inputs in this VI, right-click the cluster terminal and
select Create»Control from the shortcut menu.

© National Instruments 2015

 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

2016 ni.com
 Functions

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the graph. The default is an empty picture.

• data —

data is an array of points, where each point is a cluster of x and y pixel coordinates.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• dimensions (w,h) —

© National Instruments 2017

 Functions

dimensions specifies the top left point of the drawn bitmap.

• width —

width specifies the horizontal coordinate that increases to the right.

• height —

height specifies the vertical coordinate that increases to the bottom.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• cartesian axis attributes —

cartesian axis attributes specifies the range and format for the x- and y- axes.

If the minimum and maximum values are the same, or if you do not wire the cartesian axis
attributes input, the VI calculates the minimum and maximum values from the data.

• x minimum —

x minimum is the smallest allowable value in the range of horizontal coordinates.

• x maximum —

x maximum is the largest allowable value in the range of horizontal coordinates.

• x log? —

2018 ni.com
 Functions

x log? indicates whether the scale should be logarithmic.

• x precision —

x precision specifies the precision for the scale numbers on the x-axis.

• x format —

x format specifies the numeric format for the scale numbers on the x-axis. The default is
Decimal.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• y minimum —

y minimum is the smallest allowable value in the range of vertical coordinates.

• y maximum —

y maximum is the largest allowable value in the range of vertical coordinates.

• y log? —

y log? indicates whether the scale should be logarithmic.

• y precision —

y precision specifies the precision for the scale numbers on the y-axis.

• y format —

y format specifies the numeric format for the scale numbers on the y-axis. The default is
Decimal.

0 Decimal

© National Instruments 2019

 Functions

1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• cartesian grid cosmetics —

cartesian grid cosmetics specifies the style for the grid of the graph.

• line color —

line color specifies the color of the line.

You can wire a color box constant to this input.

• text color —

text color specifies the color of the text.

You can wire a color box constant to this input.

• tick length(3) —

tick length specifies the length of the tick marks on the edge of the scale.

• crossing axes —

crossing axes specifies if the VI draws the axes at the originating coordinate. If crossing axes
is TRUE, the VI draws the axes at the originating coordinate. If crossing axes is FALSE, the VI
draws the axes at the bottom left edge of the plot.

• visible grid? —

visible grid? specifies if the VI displays the grid in the graph. If visible grid? is TRUE, the VI
displays the grid in the graph.

• XY plot cosmetics —

XY plot cosmetics specifies the plot color, the style for the plot, and the baseline. This VI uses the

2020 ni.com
 Functions

baseline only if the XY plot type is comb plot.

• plot color —

plot color specifies the color of the plot.

The default in RGB is 255, 255, 0.

You can wire a color box constant to this input.

• XY plot type —

XY plot type specifies the style of plot to display.

0 points
1 squares
2 circles
3 connected points (default)
4 connected squares
5 connected circles
6 comb plot
7 sized scatter plot
8 sized-colored scatter plot
9 min-max lines

• baseline —

baseline specifies the baseline of a plot. The default is 0.

• [sized scatter plot cosmetics] —

sized scatter plot cosmetics specifies the range of sizes for frequency distribution points,
assuming the xy plot type is sized scatter plot or sized-colored scatter plot.

• min size —

min size specifies the smallest size to be used for points in a scatter plot.

• max size —

© National Instruments 2021

 Functions

max size specifies the largest size to be used for points in a scatter plot.

• maps to max size —

maps to max size defines the maximum size to which the uppermost point in the scatter
plot can be mapped.

• color array —

color array maps specific colors for points of each size.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

This VI ignores the values of the x minimum, x maximum, y minimum, and y

maximum subparameters of the cartesian axis attributes input. The VI ignores the
subparameters because it automatically scales the axes. Use the Plot Multi-XY VI if you
do not want to use automatic scaling.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\

Waveform and XY Plots.vi
• labview\examples\Graphics and Sound\Picture Plots\
Artificial Strip Chart.vi

Plot Multi-XY

Takes a picture and an array of plots and appends a picture of an XY graph of the data
with the plots overlaid on the same graph.

2022 ni.com
 Functions

Each plot is an array of points.

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

© National Instruments 2023

 Functions

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the plot. The default is an empty picture.

• data —

data is an array of clusters of plots, where each plot is an array of points.

• data —

data is an array of clusters of plots, where each plot is an array of points.

• x—

2024 ni.com
 Functions

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• dimensions (w,h) —

dimensions specifies the top left point of the drawn bitmap.

• width —

width specifies the horizontal coordinate that increases to the right.

• height —

height specifies the vertical coordinate that increases to the bottom.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• cartesian axis attributes —

cartesian axis attributes specifies the range and format for the x- and y- axes.

If the minimum and maximum values are the same, or if you do not wire the cartesian axis
attributes input, the VI calculates the minimum and maximum values from the data.

© National Instruments 2025

 Functions

• x minimum —

x minimum is the smallest allowable value in the range of horizontal coordinates.

• x maximum —

x maximum is the largest allowable value in the range of horizontal coordinates.

• x log? —

x log? indicates whether the scale should be logarithmic.

• x precision —

x precision specifies the precision for the scale numbers on the x-axis.

• x format —

x format specifies the numeric format for the scale numbers on the x-axis. The default is
Decimal.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• y minimum —

y minimum is the smallest allowable value in the range of vertical coordinates.

• y maximum —

y maximum is the largest allowable value in the range of vertical coordinates.

• y log? —

y log? indicates whether the scale should be logarithmic.

• y precision —

2026 ni.com
 Functions

y precision specifies the precision for the scale numbers on the y-axis.

• y format —

y format specifies the numeric format for the scale numbers on the y-axis. The default is
Decimal.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• cartesian grid cosmetics —

cartesian grid cosmetics specifies the style for the grid of the graph.

• line color —

line color specifies the color of the line.

You can wire a color box constant to this input.

• text color —

text color specifies the color of the text.

You can wire a color box constant to this input.

• tick length(3) —

tick length specifies the length of the tick marks on the edge of the scale.

• crossing axes —

crossing axes specifies if the VI draws the axes at the originating coordinate. If crossing axes
is TRUE, the VI draws the axes at the originating coordinate. If crossing axes is FALSE, the VI
draws the axes at the bottom left edge of the plot.

© National Instruments 2027

 Functions

• visible grid? —

visible grid? specifies if the VI displays the grid in the graph. If visible grid? is TRUE, the VI
displays the grid in the graph.

• XY plot cosmetics —

XY plot cosmetics specifies the plot color, the style for the plot, and the baseline. This VI uses the
baseline only if the XY plot type is comb plot.

• plot color —

plot color specifies the color of the plot.

The default in RGB is 255, 255, 0.

You can wire a color box constant to this input.

• XY plot type —

XY plot type specifies the style of plot to display.

0 points
1 squares
2 circles
3 connected points (default)
4 connected squares
5 connected circles
6 comb plot
7 sized scatter plot
8 sized-colored scatter plot
9 min-max lines

• baseline —

baseline specifies the baseline of a plot. The default is 0.

• [sized scatter plot cosmetics] —

2028 ni.com
 Functions

sized scatter plot cosmetics specifies the range of sizes for frequency distribution points,
assuming the xy plot type is sized scatter plot or sized-colored scatter plot.

• min size —

min size specifies the smallest size to be used for points in a scatter plot.

• max size —

max size specifies the largest size to be used for points in a scatter plot.

• maps to max size —

maps to max size defines the maximum size to which the uppermost point in the scatter
plot can be mapped.

• color array —

color array maps specific colors for points of each size.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\XY

Multi Plot.vi

Plot Waveform

Takes uniformly distributed data and a picture and creates a new picture that
represents a waveform graph of the data.

© National Instruments 2029

 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

2030 ni.com
 Functions

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the graph. The default is an empty picture.

• bounding rect —

bounding rect contains the upper-left and lower-right coordinates that describe a rectangle
bounding the plot, including the x- and y-axes.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

© National Instruments 2031

 Functions

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• cartesian axis attributes —

cartesian axis attributes specifies the range and format for the x- and y- axes.

If the minimum and maximum values are the same, or if you do not wire the cartesian axis
attributes input, the VI calculates the minimum and maximum values from the data.

• x minimum —

x minimum is the smallest allowable value in the range of horizontal coordinates.

• x maximum —

x maximum is the largest allowable value in the range of horizontal coordinates.

• x log? —

x log? indicates whether the scale should be logarithmic.

• x precision —

x precision specifies the precision for the scale numbers on the x-axis.

• x format —

x format specifies the numeric format for the scale numbers on the x-axis. The default is
Decimal.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal

2032 ni.com
 Functions

5 Hex

• y minimum —

y minimum is the smallest allowable value in the range of vertical coordinates.

• y maximum —

y maximum is the largest allowable value in the range of vertical coordinates.

• y log? —

y log? indicates whether the scale should be logarithmic.

• y precision —

y precision specifies the precision for the scale numbers on the y-axis.

• y format —

y format specifies the numeric format for the scale numbers on the y-axis. The default is
Decimal.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• waveform data —

waveform data contains the initial X value, the spacing between points along the x-axis, and the
y data that you want to plot.

• Xo(0) —

Xo is the initial value of x.

© National Instruments 2033

 Functions

The default is 0.

• delta X(1) —

delta X determines the spacing between points along the x-axis.

The default is 1.

• Y data —

Y data specifies the data that you want to plot along the y-axis.

• cartesian grid cosmetics —

cartesian grid cosmetics specifies the style for the grid of the graph.

• line color —

line color specifies the color of the line.

You can wire a color box constant to this input.

• text color —

text color specifies the color of the text.

You can wire a color box constant to this input.

• tick length(3) —

tick length specifies the length of the tick marks on the edge of the scale.

• crossing axes —

crossing axes specifies if the VI draws the axes at the originating coordinate. If crossing axes
is TRUE, the VI draws the axes at the originating coordinate. If crossing axes is FALSE, the VI
draws the axes at the bottom left edge of the plot.

• visible grid? —

2034 ni.com
 Functions

visible grid? specifies if the VI displays the grid in the graph. If visible grid? is TRUE, the VI
displays the grid in the graph.

• waveform plot cosmetics —

waveform plot cosmetics specifies the plot color, the style for the plot, and the baseline. The VI
uses the baseline only if the waveform plot type is comb plot or bar plot.

• plot color —

plot color specifies the color of the plot.

The default in RGB is 255, 255, 0.

You can wire a color box constant to this input.

• waveform plot type —

waveform plot type is the style of plot to display.

The default is a plot of connected points.

0 points
1 squares
2 circles
connected points
3
(default)
4 connected squares
5 connected circles
6 fill to baselines
7 comb plot
8 bar plot

• baseline —

baseline specifies the baseline of a plot. The default is 0.

• [bar style] —

© National Instruments 2035

 Functions

bar style specifies the style for bar plots, assuming the waveform plot type is bar plot.

• bar width(50%) —

bar width specifies the width of each bar relative to the rest of the graph.

• frame?(T) —

frame? indicates whether to include a frame around the bars in the graph.

• frame color(black) —

frame color is the color of the bars in the graph.

The default is black.

You can wire a color box constant to this input.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\

Waveform and XY Plots.vi
• labview\examples\Graphics and Sound\Picture Plots\
Histogram Plot.vi

Radar Plot

Takes a picture and an array of plots and appends a picture that represents the radar
plot of the data.

2036 ni.com
 Functions

You can use a radar plot to compare the performance of one set of data with another
set of data. This VI uses the Draw Legend VI as a subVI.

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

© National Instruments 2037

 Functions

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the plot. The default is an empty picture.

• data —

data is a 2D array, where each row represents a plot.

The VI draws each index in a plot on a corresponding y-scale. A straight line connects all the
points in a plot.

• plot info —

plot info specifies the name, color, and fill option for each plot.

The index of this array matches the row index in data.

2038 ni.com
 Functions

The VI uses plot name and plot color for the legend.

• plot name —

plot name is the name of the plot.

• plot color (white) —

plot color is the color of the plot.

The default in RGB is white.

You can wire a color box constant to this input.

• fill?(F) —

fill? specifies whether to fill the interior.

If FALSE (default), the VI draws only the outlines.

• axis info —

axis info specifies the label (name) of each y-axis and the minimum and maximum value of each
y-axis.

The index of this array matches the column index in data.

• label —

label is the label of the y-axis.

• max value —

max value is the maximum value of the y-axis.

• min value —

min value is the minimum value of the y-axis.

• axes info —

© National Instruments 2039

 Functions

axes info specifies the color, format and precision of the y-axes, and whether to autoscale the y-
axes.

• color (white) —

color is the color for all the y-axes.

The default in RGB is 255, 255, 255.

You can wire a color box constant to this input.

• format and precision —

format and precision specifies the format of the values on the y-axes.

• format —

format specifies the numeric format for the scale numbers.

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• precision —

precision specifies the precision for the scale numbers. The default is 1.

• autoscale? (false) —

autoscale? specifies whether to autoscale each y-axis independently.

If FALSE (default), the VI does not autoscale each y-axis.

• legend info —

legend info specifies the location of the plot legend relative to the radar plot.

2040 ni.com
 Functions

• position (none) —

position specifies where to draw the legend.

0 None (default)—The VI does not draw the legend.

1 Top
2 Right
3 Bottom
4 Left

• text color(white) —

text color is the color of the labels of the y-axes, as shown in the legend.

The default in RGB is 255, 255, 255.

You can wire a color box constant to this input.

• dimension (w,h) —

dimension (w,h) specifies the rectangle in coordinates into which the VI draws the radar plot
and legend.

• Width —

Width is the horizontal coordinate that increases to the right.

• Height —

Height is the vertical coordinate that increases to the bottom.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

© National Instruments 2041

 Functions

• y—

y is the vertical coordinate that increases to the bottom.

• new picture —

new picture is the picture that contains the plot. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Simple

Radar Plot.vi

Draw Legend

Takes a picture and adds a legend to the picture.

The Radar Plot VI uses this VI as a subVI.

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

2042 ni.com
 Functions

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

© National Instruments 2043

 Functions

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the legend. The default is an empty picture.

• plot info —

plot info specifies the name and color for each plot in the legend.

• plot name —

plot name is the name of the plot.

• plot color —

plot color is the color of the plot.

The default is black.

You can wire a color box constant to this input.

• fill?(F) —

fill? does not affect the legend and the VI ignores this value.

• text color(black) —

text color is the color of the text. The default is black.

You can wire a color box constant to this input.

• rect —

rect contains the coordinates that describe a rectangle bounding the legend.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

2044 ni.com
 Functions

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• new picture —

new picture is the picture that contains the legend. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Calc Scale Specs

Takes a specification for a Cartesian style scale and calculates the coordinates and
labels to use for the scale.

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

© National Instruments 2045

 Functions

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

2046 ni.com
 Functions

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• scale definition —

scale definition specifies the pixel coordinates and values for both ends of the scale, and the
numeric format and precision for the scale numbers.

• coordinate 1 —

coordinate 1 contains the pixel coordinates for the left of a vertical scale or the top of a
horizontal scale.

• value 1 —

value 1 contains the minimum value for the scale numbers.

• coordinate 2 —

coordinate 2 contains the pixel coordinates for the right of a vertical scale or the bottom of
a horizontal scale.

• value 2 —

value 2 contains the maximum value for the scale numbers.

• log?(F) —

log? specifies if the scale is logarithmic.

• fmt and prec —

fmt and prec specifies the numeric format and precision for the scale numbers.

• format —

format specifies the numeric format for the scale numbers.

© National Instruments 2047

 Functions

0 Decimal
1 Scientific
2 Engineering
3 Binary
4 Octal
5 Hex

• precision —

precision specifies the precision for the scale numbers. The default is 1.

• scale attributes —

scale attributes describes the format for the scale.

• horizontal —

horizontal indicates whether to draw a horizontal or vertical scale.

• left/top —

left/top indicates whether to draw the text to the left for a vertical scale and the top for a
horizontal scale (TRUE), or to the right for a vertical scale and the bottom for a horizontal
scale (FALSE).

• draw bar —

draw bar indicates whether to draw a bar as part of the scale.

• line color —

line color specifies the color of the line.

You can wire a color box constant to this input.

• text color(black) —

2048 ni.com
 Functions

text color is the color of the text. The default is black.

You can wire a color box constant to this input.

• scale specs —

scale specs is an array of clusters containing the coordinates and labels you can use in the scale.

• coordinate —

coordinate specifies the coordinates to use in the scale.

• label —

label specifies the labels to use in the scale.

Wire the scale specs output of this VI to the scale specs input of the Draw Scale VI to
draw a scale.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Simple

Scale.vi

Draw Scale

Draws a scale onto a picture.

© National Instruments 2049

 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

2050 ni.com
 Functions

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the scale. The default is an empty picture.

• scale specs —

scale specs is an array of clusters containing the coordinates and labels you can use in the scale.

Use the Calc Scale Specs VI to obtain the values for this input.

• coordinate —

coordinate specifies the coordinates to use in the scale.

• label —

label specifies the labels to use in the scale.

• constant coordinate —

constant coordinate is the location of the x coordinate in a vertical scale, or the y coordinate in a
horizontal scale.

• tick length(3) —

tick length specifies the length of the tick marks on the edge of the scale.

• scale attributes —

© National Instruments 2051

 Functions

scale attributes describes the format for the scale.

• horizontal —

horizontal indicates whether to draw a horizontal or vertical scale.

• left/top —

left/top indicates whether to draw the text to the left for a vertical scale and the top for a
horizontal scale (TRUE), or to the right for a vertical scale and the bottom for a horizontal
scale (FALSE).

• draw bar —

draw bar indicates whether to draw a bar as part of the scale.

• line color —

line color specifies the color of the line.

You can wire a color box constant to this input.

• text color(black) —

text color is the color of the text. The default is black.

You can wire a color box constant to this input.

• new picture —

new picture is the picture that contains the scale. You can wire this output to any other picture
input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can save the image data to a file using the Graphics Formats VIs.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Picture Plots\Simple

2052 ni.com
 Functions

Scale.vi

Map Setup

Uses pixel and data ranges to determine scale factors such that (a * data value) + b is
the pixel value that corresponds to that data value.

Inputs/Outputs
• log?(F) —

log? specifies if the scale is logarithmic.

• coordinate 1 —

coordinate 1 is the pixel location for the first point.

• value 1 —

value 1 is the actual data value for the first point.

• coordinate 2 —

coordinate 2 is the pixel location for the second point.

• value 2 —

value 2 is the actual data value for the second point.

• scale factors —

scale factors is the scale factor created from the two points.

Use this output as the input for other VIs such as the Map Pixel to Value VI and the Map Value to
Pixel VI.

© National Instruments 2053

 Functions

• a—

a is the value used for the scale factor equation.

• b—

b is the value used for the scale factor equation.

• log?(F) —

log? indicates if the scale is logarithmic.

Map Value to Pixel

Uses the domain value and the cluster returned by the Map Setup VI to determine a
pixel value corresponding to that domain value.

Inputs/Outputs
• scale factors —

scale factors is a cluster returned by the Map Setup VI.

• a—

a is the value used in the scale factor equation in the Map Setup VI.

• b—

b is the value used in the scale factor equation in the Map Setup VI.

• log?(F) —

log? specifies if the scale is logarithmic.

2054 ni.com
 Functions

• x—

x is the domain value.

• pixel —

pixel is the pixel value corresponding to the domain value.

Map Pixel to Value

Uses the pixel value and the cluster returned by the Map Setup VI to determine the
domain value corresponding to that pixel value.

Inputs/Outputs
• scale factors —

scale factors is a cluster returned by the Map Setup VI.

• a—

a is the value used in the scale factor equation in the Map Setup VI.

• b—

b is the value used in the scale factor equation in the Map Setup VI.

• log?(F) —

log? specifies if the scale is logarithmic.

• pixel —

pixel is the pixel value.

• x—

© National Instruments 2055

 Functions

x is the domain value corresponding to the pixel value set in pixel.

Picture Functions

Use the Picture Functions VIs to create visual representations of data. Many of these
picture VIs use clusters to define points and rectangles. The VIs related to drawing text
use clusters and enumerations to describe the font choice and the positioning of the
text.

Palette
Description
Object

Draw Point Sets a pixel in a picture to a specified color.

Changes the current pen location of a picture to the specified position or by the
Move Pen
specified amount if the position is relative.

Draw Line Draws a line from the current pen position to the specified location in a picture.

Draw
Multiple Draws multiple connected lines into a picture.
Lines

Draw
Draws a rectangle, optionally filling the interior.
Rectangle

Draw
Draws a patterned rectangle in the specified picture to create the effect of graying-out
Grayed Out
a section of the picture.
Rect

2056 ni.com
 Functions

Palette
Description
Object

Draw
Draws a rounded rectangle into a picture.
Round Rect

Draw Oval Draws an oval in the rectangle you specify, optionally filling the interior.

Draw Arc Draws an arc in a picture.

Draw Text
Draws a string into a picture.
at Point

Get Text Returns a cluster that contains the left, top, right, and bottom dimensions, in pixels, of
Rect a string.

Draw Text
Draws a string into a picture.
in Rect

Draw Circle
Draws a circle based on a specified radius and center point.
by Radius

Returns two new colors well matched to the input color for highlight and shadow
Hilite Color
coloration, based on the input color and a percentage you specify.

Converts a pixmap into a picture so you can use other Picture Functions VIs to append
Draw
drawing instructions to the image. The data type you wire to the data input
Unflattened
determines the polymorphic instance to use. If you want to convert a 4-bit or 8-bit
Pixmap
pixmap, you must manually select the polymorphic instance you want to use.

Draw
Flattened Draws a 1-, 4-, or 8-bit pixmap or a 24-bit RGB pixmap into a picture.
Pixmap

© National Instruments 2057

 Functions

Palette
Description
Object

Applies a mask to an image and returns the mask information in the mask element of
Create
image data. This VI is useful if you want to make a certain color in an image
Mask
transparent before writing the image to a 2D picture control.

Picture to Converts a picture to a cluster of image data you can use to perform certain tasks with
Pixmap the image, such as save it to a file using the Graphics Formats VIs.

Get Image Returns a subset of a source image instead of the entire image. Use the Picture to
Subset Pixmap VI to convert a picture to a cluster you can wire to image data.

Returns an empty picture. The picture input for all Picture VIs is an empty picture by
default.
Empty
Picture VI You also can create a picture constant for an empty or existing picture and wire the
constant to any picture input. You can resize the constant or right-click it and select
Visible Items»Scrollbar from the shortcut menu to view the entire picture.

Color Box
Use the color box constant to supply a constant color value to the block diagram.
Constant

Color to Resolves any color input, including system colors, into its respective red, green, and
RGB blue components.

RGB to
Converts a red, green, and blue value from 0 to 255 to the corresponding RGB color.
Color

Draw Point

Sets a pixel in a picture to a specified color.

2058 ni.com
 Functions

Inputs/Outputs
• picture —

picture is the picture to which you want to add a pixel. The default is an empty picture.

• point(x,y) —

point(x,y) is the coordinate of the pixel to set in the resulting picture relative to the current
location of the origin.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• color(black) —

color is the color of the pixel. The default is black.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

© National Instruments 2059

 Functions

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Move Pen

Changes the current pen location of a picture to the specified position or by the
specified amount if the position is relative.

Inputs/Outputs
• picture —

picture is the picture whose current pen location you want to move. The default is an empty
picture.

• new position —

new position is the point to which the pen moves in the new picture.

2060 ni.com
 Functions

If absolute coordinates? is TRUE, the pen moves to the absolute coordinate specified by new
position. If absolute coordinates? is FALSE, the pen moves relative to the current pen location in
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• absolute coordinates?(T) —

absolute coordinates? specifies whether the point new position is in absolute or relative
coordinates.

The default is absolute (TRUE).

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\2D Picture Control\

Pen Attributes And Image subsetting.vi

Draw Line

Draws a line from the current pen position to the specified location in a picture.

© National Instruments 2061

 Functions

The end point is either absolute or relative to the current position, depending on the
value of the absolute coordinates? input.

Inputs/Outputs
• picture —

picture is the picture to which you want to add the line. The default is an empty picture.

• end point —

end point is the end point of the new line.

If absolute coordinates? is TRUE, the line draws to the absolute coordinate that end point
specifies. If absolute coordinates? is FALSE, the line draws relative to the current pen location in
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• absolute coordinates?(T) —

absolute coordinates? specifies whether the point new position is in absolute or relative
coordinates.

The default is absolute (TRUE).

• color(black) —

color is the color of the pixel. The default is black.

2062 ni.com
 Functions

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\2D Picture Control\

Pen Attributes And Image subsetting.vi

© National Instruments 2063

 Functions

Draw Multiple Lines

Draws multiple connected lines into a picture.

You also can use the VI to draw color-filled polygons by passing TRUE to the fill? input.
All points are absolute coordinates.

Inputs/Outputs
• picture —

picture is the picture to which you want to add lines. The default is an empty picture.

• line endpoints —

line endpoints is an array of points describing the lines to draw.

The lines are drawn in the specified color, connecting the points in order. All coordinates are
absolute.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• fill?(F) —

fill? specifies whether to fill the interior.

If FALSE (default), the VI draws only the outlines.

• color(black) —

2064 ni.com
 Functions

color is the color of the lines.

If the interior is filled, the VI uses this color for the interior. The default is black.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Draw Rectangle

Draws a rectangle, optionally filling the interior.

© National Instruments 2065

 Functions

Inputs/Outputs
• picture —

picture is the picture to which you want to add the rectangle. The default is an empty picture.

• rect —

rect is a cluster that contains four numeric controls that describe the left, top, right, and bottom
coordinates of the outer edges of the rectangle.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• fill?(F) —

fill? specifies whether to fill the interior.

If FALSE (default), the VI draws only the outlines.

• color(black) —

color is the color of the lines.

2066 ni.com
 Functions

If the interior is filled, the VI uses this color for the interior. The default is black.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Draw Grayed Out Rect

Draws a patterned rectangle in the specified picture to create the effect of graying-out
a section of the picture.

An underlying picture shows through the holes in the pattern. The VI does not frame

© National Instruments 2067

 Functions

the rectangle.

Inputs/Outputs
• picture —

picture is the picture to which you want to add the rectangle. The default is an empty picture.

• rect —

rect is a cluster that contains four numeric controls that describe the left, top, right, and bottom
coordinates of the outer edges of the rectangle.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• color(black) —

color is the color of the pattern. In black and white, the VI uses white.

You can wire a color box constant to this input.

• new picture —

2068 ni.com
 Functions

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Draw Round Rect

Draws a rounded rectangle into a picture.

Inputs/Outputs
• oval height —

oval height is the height of an oval that defines the amount of curvature for the corners.

• oval width —

oval width is the width of an oval that defines the amount of curvature for the corners.

• picture —

picture is the picture to which you want to add the rectangle. The default is an empty picture.

• rect —

rect is a cluster that contains four numeric controls that describe the left, top, right, and bottom
coordinates of the outer edges of a rectangle that circumscribes the rounded rectangle.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

© National Instruments 2069

 Functions

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• fill?(F) —

fill? specifies whether to fill the interior.

If FALSE (default), the VI draws only the outlines.

• color(black) —

color is the color of the lines.

If the interior is filled, the VI uses this color for the interior. The default is black.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

2070 ni.com
 Functions

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

If oval height and oval width are zero, you get a normal rectangle. If they are greater
than zero, they describe how the corners of the rectangle should be rounded, as
shown in the following illustration.

Draw Oval

Draws an oval in the rectangle you specify, optionally filling the interior.

© National Instruments 2071

 Functions

Inputs/Outputs
• picture —

picture is the picture to which you want to add the oval. The default is an empty picture.

• rect —

rect is a cluster that contains four numeric controls that describe the left, top, right, and bottom
coordinates of the outer edges of the rectangle.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• fill?(F) —

fill? specifies whether to fill the interior.

If FALSE (default), the VI draws only the outlines.

• color(black) —

color is the color of the lines.

2072 ni.com
 Functions

If the interior is filled, the VI uses this color for the interior. The default is black.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Draw Arc

Draws an arc in a picture.

© National Instruments 2073

 Functions

Inputs/Outputs
• arc size[degrees] —

arc size determines the degree value of the circle you want to draw.

This value can range from -360 to 360. For example, a value of 360 creates a complete circle, and
a value of 180 creates a semicircle.

• start angle[degrees] —

start angle determines where the arc begins.

• picture —

picture is the picture to which you want to add the arc. The default is an empty picture.

• rect —

rect is a cluster that contains four numeric controls that describe the left, top, right, and bottom
coordinates of the outer edges of the rectangle.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

2074 ni.com
 Functions

bottom is the vertical coordinate of the bottom edge of the rectangle.

• fill?(F) —

fill? specifies whether to fill the rectangle. If FALSE (default), the VI draws only the arc
component and does not draw interior bounds of the wedge.

• color(black) —

color is the color of the lines.

If the interior is filled, the VI uses this color for the interior. The default is black.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

© National Instruments 2075

 Functions

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

A rectangle specifies the size of an oval that contains the arc. Thus, the arc may not fill
the whole rectangle. LabVIEW specifies the angles that describe the arc in degrees. It
can range from –360° to 360°, with positive angles appearing clockwise, and negative
angles appearing counterclockwise. Zero degrees is straight up.

LabVIEW measures all angles as though the enclosing rectangle were square. Thus, a
line from the center to the upper-right corner describes an angle of 45°. The following
illustration shows the conventions used in specifying the angle of a point of an arc.

Draw Text at Point

Draws a string into a picture.

This VI automatically calculates the bounding rectangle of the text and positions the
text with respect to the point you specify.

2076 ni.com
 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

© National Instruments 2077

 Functions

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the text string. The default is an empty picture.

• origin —

origin is the coordinate of the starting point of the text.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• alignment(left, top) —

alignment specifies the location of the text relative to the origin you specify.

• horizontal —

horizontal sets the horizontal position of the text with respect to the origin.

0 left—The horizontal component of origin specifies the left edge of the text.

2078 ni.com
 Functions

1 center—The horizontal component of the origin specifies the center of the text.
2 right—The horizontal component of origin specifies the right of the text.

• vertical —

vertical sets the vertical position of the text with respect to the origin.

0 top—The vertical component of origin specifies the top edge of the text.
1 center—The vertical component of the origin specifies the center of the text.
2 bottom—The vertical component of origin specifies the bottom of the text.

• text —

text is the string to draw in the picture.

• text color(black) —

text color is the color of the text. The default is black.

You can wire a color box constant to this input.

• BG color(transparent) —

BG color is the color of the background of the text.

The default is transparent.

You can wire a color box constant to this input.

• text orientation —

text orientation sets the orientation of the text to draw.

0 None (default)—Text appears normal.

1 Stacked—Text appears stacked.
Clockwise—Text appears rotated 90° clockwise, which results in vertical text that reads
2
downward.
Counterclockwise—Text appears rotated 90° counterclockwise, which results in vertical text
3
that reads upward.

© National Instruments 2079

 Functions

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

• text rect —

text rect is a cluster that contains coordinates that describe the left, top, right, and bottom
coordinates of the outer edges of the rectangle.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

Get Text Rect

Returns a cluster that contains the left, top, right, and bottom dimensions, in pixels, of
a string.

2080 ni.com
 Functions

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

© National Instruments 2081

 Functions

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• alignment(left, top) —

alignment specifies the location of the text relative to the origin you specify.

• horizontal —

horizontal sets the horizontal position of the text with respect to the origin.

0 left—The horizontal component of origin specifies the left edge of the text.
1 center—The horizontal component of the origin specifies the center of the text.
2 right—The horizontal component of origin specifies the right of the text.

• vertical —

vertical sets the vertical position of the text with respect to the origin.

0 top—The vertical component of origin specifies the top edge of the text.
1 center—The vertical component of the origin specifies the center of the text.
2 bottom—The vertical component of origin specifies the bottom of the text.

• origin(0,0) —

2082 ni.com
 Functions

origin is the coordinate of the starting point of the text.

• horizontal —

horizontal is the x-axis coordinate that increases to the right.

• vertical —

vertical is the y-axis coordinate that increases to the bottom.

• text —

text is the string to draw in the picture.

• text orientation —

text orientation sets the orientation of the text for which you want the bounding rectangle.

0 None (default)—Text appears normal.

1 Stacked—Text appears stacked.
Clockwise—Text appears rotated 90° clockwise. This results in vertical text that reads
2
downward.
Counterclockwise—Text appears rotated 90° counterclockwise. This results in vertical text that
3
reads upward.

• rect —

rect is a cluster that contains coordinates that describe the left, top, right, and bottom
coordinates of the outer edges of the rectangle.

Horizontal coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

© National Instruments 2083

 Functions

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

Draw Text in Rect

Draws a string into a picture.

If the string is larger than the rectangle you specify, the VI clips, or crops, the string to
the area of the rectangle.

Inputs/Outputs
• [user-specified font] —

[user-specified font] specifies the specific font characteristics for the text to draw.

The VI ignores this input unless desired font is User-specified Font.

• Font Name: —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Size —

2084 ni.com
 Functions

Size specifies the size of the font in points.

• Strikeout? —

Strikeout? specifies if the text appears in strikeout. If Strikeout? is TRUE, the text appears in
strikeout.

• Italic? —

Italic? specifies if the text appears in italics. If Italic? is TRUE, the text appears in italics.

• Underline? —

Underline? specifies if the text is underlined. If Underline? is TRUE, the text appears
underlined.

• Outline? —

Outline? specifies if the text is outlined. If Outline? is TRUE, the text appears outlined.

• Shadow? —

Shadow? specifies if the text has a shadow. If Shadow? is TRUE, the text appears in shadow.

• Bold? —

Bold? specifies if the text is bold. If Bold? is TRUE, the text appears bold.

• desired font(Application) —

desired font specifies the text font.

0 User-specified Font
Application Font
1
(default)
2 System Font
3 Dialog Font

• picture —

picture is the picture to which you want to add the text string. The default is an empty picture.

© National Instruments 2085

 Functions

• text orientation —

text orientation sets the orientation of the text to draw.

0 None (default)—Text appears normal.

1 Stacked—Text appears stacked.
Clockwise—Text appears rotated 90° clockwise, which results in vertical text that reads
2
downward.
Counterclockwise—Text appears rotated 90° counterclockwise, which results in vertical text
3
that reads upward.

• rect —

rect contains the upper-left and lower-right coordinates that describe a rectangle bounding the
text.

The VI clips text to the coordinates of this rectangle. Horizontal coordinates increase to the right,
and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• text —

text is the string to draw in the picture.

• text color(black) —

text color is the color of the text. The default is black.

2086 ni.com
 Functions

You can wire a color box constant to this input.

• BG color(transparent) —

BG color is the color of the background of the text.

The default is transparent.

You can wire a color box constant to this input.

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

Draw Circle by Radius

Draws a circle based on a specified radius and center point.

Inputs/Outputs
• arc size(360) —

arc size determines the degree value of the circle you want to draw.

This value can range from -360 to 360. For example, a value of 360 creates a complete circle, and
a value of 180 creates a semicircle.

© National Instruments 2087

 Functions

• start angle(0) —

start angle determines where the arc begins.

• picture —

picture is the picture to which you want to add the circle. The default is an empty picture.

• radius —

radius determines the size of the circle, in pixels.

If, for example, this value is 40, the radius of the resulting circle is 40 pixels.

• pixel center —

pixel center contains the coordinates around which the VI draws the circle.

• horizontal —

horizontal is the pixel center of the circle relative to the x-coordinate of the current origin.

• vertical —

vertical is the pixel center of the circle relative to the y-coordinate of the current origin.

• fill?(F) —

fill? specifies whether to fill the interior.

If FALSE (default), the VI draws only the outlines.

• color(black) —

color sets the pen color to use when drawing the oval.

If unwired, the VI uses the last color specified as the pen color.

You can wire a color box constant to this input.

• pen —

pen sets the width and style of the pen the VI uses to draw the picture.

2088 ni.com
 Functions

• Width —

Width sets the width in pixels of the pen the VI uses to draw the picture.

• Style —

Style sets the style of the line the VI uses to draw the picture.

Solid
0
(default)
1 Dash
2 Dot
3 DashDot
4 DashDotDot

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

You also can wire this output to the Picture to Pixmap VI to obtain an image data cluster. You
then can use the Graphics Formats VIs to save the image data to a file. You can wire this output
to the Concatenate Strings function to concatenate the output from multiple Picture Functions
VIs so that they draw on a single picture control.

The Draw Circle by Radius VI uses the information you specify and calls the Draw Oval
VI.

A rectangle specifies the size of an oval that contains the arc. Thus, the arc may not fill
the whole rectangle. LabVIEW specifies the angles that describe the arc in degrees. It
can range from –360° to 360°, with positive angles appearing clockwise, and negative
angles appearing counterclockwise. Zero degrees is straight up.

LabVIEW measures all angles as though the enclosing rectangle were square. Thus, a
line from the center to the upper-right corner describes an angle of 45°. The following
illustration shows the conventions used in specifying the angle of a point of an arc.

© National Instruments 2089

 Functions

Hilite Color

Returns two new colors well matched to the input color for highlight and shadow
coloration, based on the input color and a percentage you specify.

You can use the highlight colors to create three-dimensionally shaded objects.

Inputs/Outputs
• Color In —

Color In is the input color on which to base the returned highlight and shadow colors.

You can wire a color box constant to this input.

• Percentage(30) —

Percentage determines the degree of highlighting and shadow in the new colors.

The default is 30 percent.

• Hilite —

Hilite is the new color matched as a highlight to the input color.

• Shadow —

Shadow is the new color matched as a shadow to the input color.

2090 ni.com
 Functions

Draw Unflattened Pixmap

Converts a pixmap into a picture so you can use other Picture Functions VIs to append
drawing instructions to the image. The data type you wire to the data input determines
the polymorphic instance to use. If you want to convert a 4-bit or 8-bit pixmap, you
must manually select the polymorphic instance you want to use.

• Draw True-Color Pixmap VI

• Draw 1-Bit Pixmap VI
• Draw 4-Bit Pixmap VI
• Draw 8-Bit Pixmap VI

Draw True-Color Pixmap VI

Converts a pixmap into a picture so you can use other Picture Functions VIs to append
drawing instructions to the image. The data type you wire to the data input determines
the polymorphic instance to use. If you want to convert a 4-bit or 8-bit pixmap, you
must manually select the polymorphic instance you want to use.

Inputs/Outputs
• picture —

picture is the picture to which you want to add the pixmap. The default is an empty picture.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

© National Instruments 2091

 Functions

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• data (RGB format) —

data is a 2D array of 32-bit unsigned integers that describes the color of each pixel in the image
in raster order.

Each pixel has three bytes to describe its color. The first byte for each pixel describes the red
value, the second byte describes the green value, and the third byte describes the blue value.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first byte
describes the first eight pixels, the second byte describes the next eight pixels, and so on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each pixel
in the image, LabVIEW draws any pixels missing from the array without transparency.

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

Draw 1-Bit Pixmap VI

Converts a pixmap into a picture so you can use other Picture Functions VIs to append
drawing instructions to the image. The data type you wire to the data input determines
the polymorphic instance to use. If you want to convert a 4-bit or 8-bit pixmap, you
must manually select the polymorphic instance you want to use.

2092 ni.com
 Functions

Inputs/Outputs
• picture —

picture is the picture to which you want to add the pixmap. The default is an empty picture.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• data —

data is a 2D array of Boolean inputs in which each input represents a single pixel.

A value of FALSE in data corresponds to element 0 in color table. A value of TRUE in data
corresponds to element 1 in color table.

• color table —

color table is an array of two colors to which the array of data maps.

If data is FALSE, the default is black. If data is TRUE, the default is white.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first byte
describes the first eight pixels, the second byte describes the next eight pixels, and so on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,

© National Instruments 2093

 Functions

LabVIEW draws all pixels without transparency. If the array does not contain a bit for each pixel
in the image, LabVIEW draws any pixels missing from the array without transparency.

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

Draw 4-Bit Pixmap VI

Converts a pixmap into a picture so you can use other Picture Functions VIs to append
drawing instructions to the image. The data type you wire to the data input determines
the polymorphic instance to use. If you want to convert a 4-bit or 8-bit pixmap, you
must manually select the polymorphic instance you want to use.

Inputs/Outputs
• picture —

picture is the picture to which you want to add the pixmap. The default is an empty picture.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

2094 ni.com
 Functions

y is the vertical coordinate that increases to the bottom.

• data —

data is a 2D array of 8-bit unsigned integers that describes the color of each pixel in the image in
raster order.

Each element in data specifies the index of the corresponding color in color table. Thus, valid
values in data are the indices of the color table array, or 0 through 15.

• color table —

color table is an array of up to 16 colors to which the array of data maps.

color table stores 32-bit RGB values where the most-significant byte is zero, followed in order by
red, green, and blue values. If unwired, the VI uses the default LabVIEW 16-color palette.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first byte
describes the first eight pixels, the second byte describes the next eight pixels, and so on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each pixel
in the image, LabVIEW draws any pixels missing from the array without transparency.

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

Draw 8-Bit Pixmap VI

Converts a pixmap into a picture so you can use other Picture Functions VIs to append
drawing instructions to the image. The data type you wire to the data input determines
the polymorphic instance to use. If you want to convert a 4-bit or 8-bit pixmap, you
must manually select the polymorphic instance you want to use.

© National Instruments 2095

 Functions

Inputs/Outputs
• picture —

picture is the picture to which you want to add the pixmap. The default is an empty picture.

• top left point(0, 0) —

top left point specifies in coordinates where to place the top-left corner of the image in the new
picture.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• data —

data is a 2D array of 8-bit unsigned integers that describes the color of each pixel in the image in
raster order.

Each element in data specifies the index of the corresponding color in color table. Thus, valid
values in data are the indices of the color table array, or 0 through 255.

• color table —

color table is an array of up to 256 colors to which the array of data maps.

color table stores 32-bit RGB values where the most-significant byte is zero, followed in order by
red, green, and blue values. If unwired, the VI uses the default LabVIEW 256-color palette.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first byte

2096 ni.com
 Functions

describes the first eight pixels, the second byte describes the next eight pixels, and so on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each pixel
in the image, LabVIEW draws any pixels missing from the array without transparency.

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

Draw Flattened Pixmap

Draws a 1-, 4-, or 8-bit pixmap or a 24-bit RGB pixmap into a picture.

This VI takes a 1D array of bytes as input and assumes the user completes all packing
and padding.

Inputs/Outputs
• picture —

picture is the picture to which you want to add the array of data. The default is an empty picture.

• image data —

image data describes the image you want to draw or manipulate.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to

© National Instruments 2097

 Functions

describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255.

2098 ni.com
 Functions

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle in
which you want to draw the image.

The VI clips the image to the width and height of the rectangle. The bottom and right edges
of the rectangle bounds do not contain image pixels. Horizontal coordinates increase to the
right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• new picture —

new picture is the picture that contains the new image. You can wire this output to any other
picture input to add more drawing instructions to the picture.

© National Instruments 2099

 Functions

Note This VI interprets 32-bit images as 24-bit images.

You can use this VI with one of the Graphics Formats VIs that reads graphics files in a
flattened format. You also can use the Flatten Pixmap VI to produce flattened pixmap
data. Use the Unflatten Pixmap VI to unflatten data for use with one of the other VIs
used to draw a pixmap.

The Draw Flattened Pixmap VI expects all images to be padded with a 2-byte
boundary. The Draw Flattened Pixmap VI does not pad images. The various Graphics
Formats VIs which load images also pad images appropriately for use in the Draw
Flattened Pixmap VI. If you choose to upload your image in a different way, you need to
pad the data with a 2-byte boundary yourself before using the Draw Flattened Pixmap
VI.

Create Mask

Applies a mask to an image and returns the mask information in the mask element of
image data. This VI is useful if you want to make a certain color in an image
transparent before writing the image to a 2D picture control.

Inputs/Outputs
• image data —

image data returns information about the image so you can use the Draw Flattened Pixmap VI to
draw it as a picture.

• image type —

image type is reserved for future use.

• image depth —

2100 ni.com
 Functions

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

© National Instruments 2101

 Functions

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

The VI clips the image to the width and height of the rectangle. The bottom and right edges
of the rectangle bounds do not contain image pixels. Horizontal coordinates increase to the
right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• Mask Color (Black) —

Mask Color is the color in the image you want to appear transparent for 24-bit, 8-bit, and 4-bit
images.

You can wire a color box constant to this input.

• 1-Bit Mask Value (T) —

2102 ni.com
 Functions

If 1-Bit Mask Value is TRUE (default), the VI draws all elements in the image array with an index
of 1 as transparent. If FALSE, the VI draws all elements with an index of 0 as transparent.

The VI ignores this input if image data does not describe a 1-bit image.

• Combine Masks? (F) —

If Combine Masks? is TRUE, the VI combines any existing mask information for the image and
the mask information you wire to this VI and applies all the mask information to the image. If
FALSE (default), the VI applies only the mask information you wire to this VI.

• image data —

image data describes the image you want to draw or manipulate.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in

© National Instruments 2103

 Functions

image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

The size of the array might be larger than expected due to padding.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255.

If image depth is 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle in
which you want to draw the image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the

2104 ni.com
 Functions

bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

Use the Flatten Pixmap VI to convert a pixmap to a cluster you can wire to image data.
If the image is 4-bit, 8-bit, or 24-bit, wire a color to the Mask Color input. If the image is
1-bit, wire a value to the 1-Bit Mask Value input.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\2D Picture Control\

Using Mask with Picture.vi

Picture to Pixmap

Converts a picture to a cluster of image data you can use to perform certain tasks with
the image, such as save it to a file using the Graphics Formats VIs.

© National Instruments 2105

 Functions

Inputs/Outputs
• picture —

picture is the picture you want to convert to a pixmap.

• rect —

rect is a cluster that contains coordinates that describe the bounding rectangle of the image you
want to convert.

The default is to return the entire image. Horizontal coordinates increase to the right, and
vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• depth —

depth specifies the color depth of the image, which is the number of bits to use to describe the
color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per pixel.

The default is 24.

• Background Color —

2106 ni.com
 Functions

Background Color sets the background color of the image.

• new picture —

new picture returns picture unchanged.

• image data —

image data returns information about the pixmap so you can use the Graphics Formats VIs to
save the pixmap to a file.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

© National Instruments 2107

 Functions

The size of the array might be larger than expected due to padding.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the
bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

2108 ni.com
 Functions

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

Get Image Subset

Returns a subset of a source image instead of the entire image. Use the Picture to
Pixmap VI to convert a picture to a cluster you can wire to image data.

If you wire 32-bit image data to this VI, the VI strips the alpha channel and returns
24-bit image data.

Inputs/Outputs
• image data —

image data describes the image you want to draw or manipulate.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to

© National Instruments 2109

 Functions

describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255.

2110 ni.com
 Functions

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle in
which you want to draw the image.

The VI clips the image to the width and height of the rectangle. The bottom and right edges
of the rectangle bounds do not contain image pixels. Horizontal coordinates increase to the
right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• subset rect —

subset rect is a cluster that contains coordinates that describe the bounding rectangle of the
image subset.

If the coordinates do not describe a valid rectangle, the VI coerces the coordinates to a valid
rectangle and returns the coerced coordinates in true subset rect.

© National Instruments 2111

 Functions

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• image subset —

image subset returns information about the image subset so you can use the Draw Flattened
Pixmap VI to draw the image as a picture or use the Graphics Formats VIs to save the image to a
file.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte

2112 ni.com
 Functions

describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

The size of the array might be larger than expected due to padding.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette.

• Rectangle —

© National Instruments 2113

 Functions

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the
bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• true subset rect —

true subset rect is a cluster that contains coordinates that describe the bounding rectangle of
the image subset returned by the VI.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

2114 ni.com
 Functions

bottom is the vertical coordinate of the bottom edge of the rectangle.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\2D Picture Control\

Pen Attributes And Image subsetting.vi

Empty Picture VI

Returns an empty picture. The picture input for all Picture VIs is an empty picture by
default.

You also can create a picture constant for an empty or existing picture and wire the
constant to any picture input. You can resize the constant or right-click it and select
Visible Items»Scrollbar from the shortcut menu to view the entire picture.

Inputs/Outputs
• empty picture —

empty picture is the output.

Color Box Constant

Use the color box constant to supply a constant color value to the block diagram.

Use the color picker to set the color in the color box constant.

You cannot change the value of the color box constant while the VI runs. You can assign

© National Instruments 2115

 Functions

a label to this constant.

Color to RGB

Resolves any color input, including system colors, into its respective red, green, and
blue components.

To perform a task such as color arithmetic with symbolic colors, you must convert the
colors to their red, green, and blue components.

Inputs/Outputs
• Color —

Color is the color that you want to convert to its respective red, green, and blue components.

• Resolved Color —

resolved color is the resolved color in RGB format.

• R—

R is the red component of the RGB value, 0 to 255.

• G—

G is the green component of the RGB value, 0 to 255.

• B—

B is the blue component of the RGB value, 0 to 255.

2116 ni.com
 Functions

RGB to Color

Converts a red, green, and blue value from 0 to 255 to the corresponding RGB color.

Inputs/Outputs
• R—

R is the red value for the color, 0 to 255.

• G—

G is the green value for the color, 0 to 255.

• B—

B is the blue value for the color, 0 to 255.

• Color —

Color is the RGB color value that corresponds to R, G, and B.

Graphics Formats

Use the Graphics Formats VIs to retrieve or store image data in BMP, JPEG, or PNG
image files.

Palette Object Description

Write JPEG
Writes a JPEG file.
File

© National Instruments 2117

 Functions

Palette Object Description

Write PNG File Writes a PNG file.

Write BMP File Writes a Windows bitmap file.

Read JPEG Reads a JPEG file and creates the data necessary to display the file in a picture
File control.

Reads a PNG file and creates the data necessary to display the file in a picture
Read PNG File
control.

Reads a Windows bitmap file and creates the data necessary to display the file in a
Read BMP File
picture control.

Flatten
Converts pixmap data from a 2D array to a 1D array.
Pixmap

Unflatten
Converts a cluster of image data into a 2D array.
Pixmap

Write JPEG File

Writes a JPEG file.

If you want to write a pixmap to a file, use the Flatten Pixmap VI to convert the data to
an image data cluster before using this VI. If you want to write a picture to a file, use
the Picture to Pixmap VI to convert the data to an image data cluster before using this
VI.

2118 ni.com
 Functions

Inputs/Outputs
• quality (80) —

quality specifies the level of quality you want for the JPEG using the IJG JPEG library scale,
which ranges from 0 to 100. The default is 80.

The scale balances image quality and file size. A value in the 75–95 range produces a compressed
file with a high-quality image, and a value below 50 produces a smaller file size with a low-
quality image.

• path to JPEG file —

path to JPEG file specifies the path to and name of the JPEG file to write.

If you do not specify a path, LabVIEW displays a file dialog box so the user can navigate to the
file.

• image data —

image data describes the image you want to draw or manipulate.

If you wire 32-bit image data to this VI, the VI returns a 24-bit pixmap.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.

© National Instruments 2119

 Functions

The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255. In the Write File VIs (BMP, JPEG, and PNG),
LabVIEW does not have an automatic color table. Use the colors input even for image depth
of lower bit value to ensure the best performance of the Write File VIs.

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

2120 ni.com
 Functions

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

The bottom and right edges of the rectangle bounds do not contain image pixels. Horizontal
coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path —

path specifies the path to the JPEG file.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2121

 Functions

Write PNG File

Writes a PNG file.

If you want to write a pixmap to a file, use the Flatten Pixmap VI to convert the data to
an image data cluster before using this VI. If you want to write a picture to a file, use
the Picture to Pixmap VI to convert the data to an image data cluster before using this
VI.

Inputs/Outputs
• compression (default) —

compression specifies the level of file compression you want for the PNG file.

The quality of the graphic is not affected by the compression, but the graphic file size and speed
of compression are affected by this value. Valid values range from –1 to 9 and balance file
compression with speed. The following table lists example values for compression.

-1 Good compression and speed (default)

0 No compression
1 Best speed with compression
9 Best compression

• path to PNG file —

path to PNG file specifies the path to and name of the PNG file to write.

If you do not specify a path, LabVIEW displays a file dialog box so the user can navigate to the
file.

• image data —

image data describes the image you want to draw or manipulate.

If you wire 32-bit image data to this VI, the VI returns a 24-bit pixmap.

2122 ni.com
 Functions

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

© National Instruments 2123

 Functions

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255. In the Write File VIs (BMP, JPEG, and PNG),
LabVIEW does not have an automatic color table. Use the colors input even for image depth
of lower bit value to ensure the best performance of the Write File VIs.

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

The bottom and right edges of the rectangle bounds do not contain image pixels. Horizontal
coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error in (no error) —

2124 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path —

path specifies the path to the PNG file.

• error out —

error out contains error information. This output provides standard error out functionality.

Write BMP File

Writes a Windows bitmap file.

If you want to write a pixmap to a file, use the Flatten Pixmap VI to convert the data to
an image data cluster before using this VI. If you want to write a picture to a file, use
the Picture to Pixmap VI to convert the data to an image data cluster before using this
VI.

Inputs/Outputs
• path to BMP file —

path to BMP file specifies the path to and name of the bitmap file to write.

If you do not specify a path, LabVIEW displays a file dialog box so the user can navigate to the
file.

• image data —

image data describes the image you want to draw or manipulate.

If you wire 32-bit image data to this VI, the VI returns a 24-bit pixmap.

© National Instruments 2125

 Functions

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

2126 ni.com
 Functions

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255. In the Write File VIs (BMP, JPEG, and PNG),
LabVIEW does not have an automatic color table. Use the colors input even for image depth
of lower bit value to ensure the best performance of the Write File VIs.

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

The bottom and right edges of the rectangle bounds do not contain image pixels. Horizontal
coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error in (no error) —

© National Instruments 2127

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path —

path specifies the path of the pixmap.

• error out —

error out contains error information. This output provides standard error out functionality.

Read JPEG File

Reads a JPEG file and creates the data necessary to display the file in a picture control.

Use the Draw Flattened Pixmap VI to display the bitmap you acquire with this VI. Use
the Unflatten Pixmap VI to work with the data as a 2D array.

Note This VI automatically reads JPEG files as 24-bit images.

Inputs/Outputs
• path to JPEG file —

path to JPEG file specifies the path to and name of the JPEG file to read.

If you do not specify a path, LabVIEW displays a file dialog box so the user can navigate to the
file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• use 8 bit color table —

2128 ni.com
 Functions

use 8 bit color table reads the JPEG file at an 8 bit per pixel image depth instead of 24 bit per
pixel image depth. The default value is FALSE.

• path —

path specifies the path of the pixmap.

• image data —

image data returns information about the image so you can use the Draw Flattened Pixmap VI to
draw it as a picture.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

The size of the array might be larger than expected due to padding.

• mask —

© National Instruments 2129

 Functions

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on. In this VI, the mask array is always empty.

Since the array is empty, LabVIEW draws all pixels without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the
bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

2130 ni.com
 Functions

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error out —

error out contains error information. This output provides standard error out functionality.

Read PNG File

Reads a PNG file and creates the data necessary to display the file in a picture control.

Use the Draw Flattened Pixmap VI to display the bitmap you acquire with this VI. Use
the Unflatten Pixmap VI to work with the data as a 2D array.

Note This VI can read 32-bit PNG files.

Inputs/Outputs
• path to PNG file —

path to PNG file specifies the path to and name of the PNG file to read.

If you do not specify a path, LabVIEW displays a file dialog box so the user can navigate to the
file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Transparency Thresh —

© National Instruments 2131

 Functions

Transparency Thresh incorporates alpha information for a 32-bit PNG image into the mask of
the resulting image data. LabVIEW treats as opaque any alpha values equal to or greater than
Transparency Thresh. LabVIEW treats all other alpha values as fully transparent. The value of
Transparency Thresh must be between 0 and 255.

• path —

path specifies the path of the pixmap.

• image data —

image data returns information about the image so you can use the Draw Flattened Pixmap VI to
draw it as a picture.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, 24, and 32 bits
per pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 32, each pixel has three bytes to describe its color, and a fourth byte to
describe transparency. The fourth byte is known as the 8-bit alpha channel. The first byte
for each pixel describes the red value, the second byte describes the green value, and the
third byte describes the blue value.

If image depth is 24, each pixel has three bytes to describe its color. When the image depth
is 24, the behavior is similar to when image depth is 32. However, 24-bit images do not
have an extra fourth byte to describe transparency.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most

2132 ni.com
 Functions

significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

The size of the array might be larger than expected due to padding.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

In 32-bit cases, the mask is always filled. For all other cases in this VI, the mask array is
empty. If the array is empty, LabVIEW draws all pixels without transparency. If the array does
not contain a bit for each pixel in the image, LabVIEW draws any pixels missing from the
array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

If image depth is 32 or 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the

© National Instruments 2133

 Functions

image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the
bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error out —

error out contains error information. This output provides standard error out functionality.

You might receive an error if you attempt to read a PNG file whose image type is not
supported in LabVIEW. LabVIEW supports JPG, BMP, and PNG images. To load a PNG
image with an unsupported image type in LabVIEW, use a third-party graphics format
converter to save the image as a standard file format that LabVIEW can load (JPG, BMP,
or PNG).

Read BMP File

Reads a Windows bitmap file and creates the data necessary to display the file in a
picture control.

Use the Draw Flattened Pixmap VI to display the bitmap you acquire with this VI. Use

2134 ni.com
 Functions

the Unflatten Pixmap VI to work with the data as a 2D array.

Inputs/Outputs
• path to BMP file —

path to BMP file specifies the path to and name of the bitmap file to read.

If you do not specify a path, LabVIEW displays a file dialog box so the user can navigate to the
file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path —

path specifies the path of the pixmap.

• image data —

image data returns information about the image so you can use the Draw Flattened Pixmap VI to
draw it as a picture.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

© National Instruments 2135

 Functions

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

The size of the array might be larger than expected due to padding.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on. In this VI, the mask array is always empty.

Since the array is empty, LabVIEW draws all pixels without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

2136 ni.com
 Functions

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette. In this VI, the array is always filled up for 8, 4, and 1 bit cases.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the
bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error out —

error out contains error information. This output provides standard error out functionality.

Flatten Pixmap

Converts pixmap data from a 2D array to a 1D array.

You can write the resulting 1D array to a file or use the low-level Draw Flattened
Pixmap VI to view it.

© National Instruments 2137

 Functions

Inputs/Outputs
• top left —

top left specifies in coordinates where to place the top-left corner of the image.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• 24-bit pixmap —

24-bit pixmap is the 2D array of data to convert to image data.

The dimensions of the image data match the dimensions of this array.

• 8-bit pixmap —

8-bit pixmap is the 2D array of data to convert to image data.

The dimensions of the image data match the dimensions of this array. The VI uses the data as
indexes into the color array.

• 4-bit pixmap —

4-bit pixmap is the 2D array of data to convert to image data.

The dimensions of the image data match the dimensions of this array. The VI uses the data as
indexes into the color array.

• 1-bit pixmap —

2138 ni.com
 Functions

1-bit pixmap is the 2D array of data to convert to image data.

The dimensions of the image data match the dimensions of this array. Elements that are FALSE
map to element 0 in the color table. Elements that are TRUE map to element 1 in the color table.

• colors —

colors is an array of RGB color values that correspond to the values in the pixmap input you
wire. Which pixmap input you wire determines how LabVIEW interprets the value of this input.

If you wire data to 24-bit pixmap, LabVIEW ignores this input. If you wire data to 8-bit pixmap,
the array can have 256 elements. If you wire data to 4-bit pixmap, the array can have 16
elements. If you wire data to 1-bit pixmap, the array can have 2 elements. If the colors array is
empty for any depth other than 24 bits per pixel, the image uses the default LabVIEW color
palette.

• mask —

mask is a 1D array that describes mask information for each pixel.

If the mask array is empty, LabVIEW draws all resulting pixels without transparency.

• image data —

image data returns information about the pixmap so you can use the Draw Flattened Pixmap VI
to draw the pixmap as a picture or use the Graphics Formats VIs to save the pixmap to a file.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.

© National Instruments 2139

 Functions

The value of image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each bit
corresponds to an element in colors, which stores 32-bit RGB values where the most
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

The size of the array might be larger than expected due to padding.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this output.

If image depth is 24, LabVIEW ignores this output.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

2140 ni.com
 Functions

If the array is empty for any depth other than 24 bits per pixel, the image is using the default
LabVIEW color palette.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

Horizontal coordinates increase to the right, and vertical coordinates increase to the
bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

Unflatten Pixmap

Converts a cluster of image data into a 2D array.

© National Instruments 2141

 Functions

Inputs/Outputs
• image data —

image data describes the image you want to draw or manipulate.

If you wire 32-bit image data to this VI, the VI returns a 24-bit pixmap.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first

2142 ni.com
 Functions

byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255.

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle of the
image.

The bottom and right edges of the rectangle bounds do not contain image pixels. Horizontal
coordinates increase to the right, and vertical coordinates increase to the bottom.

• left —

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

© National Instruments 2143

 Functions

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• top left —

top left is a cluster that contains a horizontal (x) and a vertical (y) component.

• x—

x is the horizontal coordinate that increases to the right.

• y—

y is the vertical coordinate that increases to the bottom.

• 24-bit pixmap —

24-bit pixmap returns the 2D array of data to draw as a pixmap.

The dimensions of the pixmap match the dimensions of this array.

• 8-bit pixmap —

8-bit pixmap returns the 2D array of data to draw as a pixmap.

The dimensions of the pixmap match the dimensions of this array. The VI uses the data as
indexes in the colors output.

• 4-bit pixmap —

4-bit pixmap returns the 2D array of data to draw as a pixmap.

The dimensions of the pixmap match the dimensions of this array. The VI uses the data as
indexes in the colors output.

• 1-bit pixmap —

2144 ni.com
 Functions

1-bit pixmap returns the 2D array of data to draw as a bitmap.

The dimensions of the bitmap match the dimensions of this array. Elements that are FALSE map
to element 0 in the colors output and elements that are TRUE map to element 1.

• colors —

colors is an array of RGB color values that correspond to the values in the pixmap output.

For the 24-bit pixmap, LabVIEW ignores this output. For the 8-bit pixmap, the array can have
256 elements. For the 4-bit pixmap, the array can have 16 elements. For the 1-bit pixmap, the
array can have 2 elements.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first byte
describes the first eight pixels, the second byte describes the next eight pixels, and so on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each pixel
in the image, LabVIEW draws any pixels missing from the array without transparency.

When you use a Graphics Formats VI to read a graphics file, the VI returns the image
data in a cluster. Use the Draw Unflattened Pixmap VI to display the data directly or use
the Unflatten Pixmap VI to convert the data to a more useful 2D representation.

In this VI, only one of the various pixmap outputs (24-bit, 8-bit, 4-bit, or 1-bit) is valid at
a time. In other words, this VI will not produce an output of two different pixmap
values.

Beep (Windows)

Causes the system to issue an audible tone. (Windows Vista 64-bit) This VI might not
work correctly if use system alert? is FALSE.

© National Instruments 2145

 Functions

Inputs/Outputs
• frequency (Hz) —

frequency (Hz) is the frequency of the tone in Hertz. LabVIEW ignores this parameter when use
system alert? is TRUE.

• duration (msec) —

duration (msec) is the duration of the tone in milliseconds. LabVIEW ignores this parameter
when use system alert? is TRUE.

• use system alert? (T) —

use system alert? specifies whether LabVIEW uses the default system alert and ignores
frequency (Hz) and duration (msec). If FALSE, this VI makes a synchronous beep using the
specified frequency and duration.

The default is TRUE.

Sound

Use the Sound VIs to play sounds.

(Windows) You must have DirectX 8.0 or later to use the Sound VIs.

(Linux) You must have the Open Sound System (OSS) driver to use the Sound VIs.
LabVIEW searches for input and output devices by looking for files named /dev/dsp
or /dev/dspX, where X is an integer between 0 and 16. LabVIEW attempts to open
each input and output device. If LabVIEW cannot detect the sound card, check that a
device file named /dev/dsp or /dev/dspX exists on the local system and that you
have permission to read from and write to the device. If you moved this device to a
location other than the default, LabVIEW can work with a symbolic link.

2146 ni.com
 Functions

Palette Object Description

Output Use the Sound Output VIs to configure and control a sound output device.

Input Use the Sound Input VIs to configure and control a sound input device.

Files Use the Sound Files VIs to create and retrieve PC wave files (.wav).

Output

Use the Sound Output VIs to configure and control a sound output device.

(Windows) You must have DirectX 8.0 or later to use the Sound Output VIs.

(Linux) You must have the Open Sound System (OSS) driver to use this VI. LabVIEW
searches for input and output devices by looking for files named /dev/dsp or /dev/
dspX, where X is an integer between 0 and 16. LabVIEW attempts to open each input
and output device. If LabVIEW cannot detect the sound card, check that a device file
named /dev/dsp or /dev/dspX exists on the local system and that you have
permission to read from and write to the device. If you moved this device to a location
other than the default, LabVIEW can work with a symbolic link.

Palette
Description
Object

Play Plays data from the sound output device using finite sampling. This Express VI
Waveform automatically configures an output task and clears the task after the output completes.

Sound
Output Configures a sound output device to generate data. Use the Sound Output Write VI to
Configure

© National Instruments 2147

 Functions

Palette
Description
Object

write the data to the device.

Sound
Starts playback from the device. This VI is necessary only if the Sound Output Stop VI
Output
has previously been called.
Start

Sound Writes data to a sound output device. You must use the Sound Output Configure VI to
Output configure the device if you are writing continuously. You must manually select the
Write polymorphic instance you want to use.

Sound
Stops the device from playing sound from the buffer. Use the Sound Output Clear VI to
Output
clear the data in the buffer. Use the Sound Output Start VI to restart output.
Stop

Sound
Stops the device from playing sound, clears the buffer, returns the task to the default
Output
state, and clears the resources associated with the task. The task becomes invalid.
Clear

Sound
Output Waits until all of the sound is played by the output device.
Wait
Sound
Output Returns information about the current state of a sound output task.
Info
Sound
Output
Sets the volume at which the sound output device plays.
Set
Volume
Play
Sound Opens a file and starts playing it immediately.
File

2148 ni.com
 Functions

Play Waveform
Plays data from the sound output device using finite sampling. This Express VI
automatically configures an output task and clears the task after the output
completes.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Dialog Box Options

Option Description

Device Lists the sound devices you have connected.

Contains the following options:

• Min sample rate (Hz)—

Returns the minimum output sample rate the selected device supports.

• Max sample rate (Hz)—

Device Returns the maximum output sample rate the selected device supports.
capabilities
• Resolution (bits)—

Specifies the quality of each sample in bits. The default is 16 bits.

• #Channels—

Specifies the number of channels. 1 is Mono, and 2 is Stereo.

Test Device Tests the selected sound device by playing a 500 Hz tone for approximately 1/4

© National Instruments 2149

 Functions

Option Description

second.

Inputs/Outputs
• Device —

Lists the sound devices you have connected.

• error in —

The error in cluster can accept error information wired from VIs previously called. Use this
information to decide if any functionality should be bypassed in the event of errors from other
VIs. The pop-up option Explain Error (or Explain Warning) gives more information about the
error displayed.

• Data —

Specifies the data this Express VI plays.

You can wire a waveform, an array of waveforms (one waveform per channel), or the Data output
of the Acquire Sound Express VI to this input. The Play Waveform Express VI uses the timing
information the waveform data type specifies to play back sound.

• error out —

The error out cluster passes error or warning information out of a VI to be used by other VIs. The
pop-up option Explain Error (or Explain Warning) gives more information about the error
displayed.

Components

Specifies the number of channels. 1 is Mono, and 2 is Stereo.

Specifies the quality of each sample in bits. The default is 16 bits.

Returns the maximum output sample rate the selected device supports.

Returns the minimum output sample rate the selected device supports.

2150 ni.com
 Functions

Lists the sound devices you have connected.

The error out cluster passes error or warning information out of a VI to be used by
other VIs. The pop-up option Explain Error (or Explain Warning) gives more
information about the error displayed.

The source string describes the origin of the error or warning. The pop-up option
Explain Error (or Explain Warning) gives more information about the error displayed.

The code input identifies the error or warning. The pop-up option Explain Error (or
Explain Warning) gives more information about the error displayed.

The status boolean is either TRUE (X) for an error, or FALSE (checkmark) for no error or
a warning. The pop-up option Explain Error (or Explain Warning) gives more
information about the error displayed.

Tests the selected sound device by playing a 500 Hz tone for approximately 1/4 second.

Sound Output Configure

Configures a sound output device to generate data. Use the Sound Output Write VI to
write the data to the device.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel in the buffer.

© National Instruments 2151

 Functions

Use a large number of samples for continuous operations. Use a smaller number of samples if
you want to use less memory.

• sample mode —

sample mode specifies whether you intend to write just once (Finite Samples) or continuously
(Continuous Samples).

In Finite Samples mode, call Sound Output Write only until you have written the number of
samples specified in number of samples/ch. In Continuous Samples mode, you can call Sound
Output Write repeatedly as needed.

• device ID —

device ID is the input or output device you access for a sound operation. In general, most users
should select the default value of 0.

The value ranges from 0 to n–1, where n is the number of input or output devices on the
computer.

• sound format —

sound format sets the playing rate, the number of channels, and the bits per sample of the
sound operation. The values for each of these controls is dependent on your sound card.

Note Setting sample rate (S/s) and bits per sample high uses more of the computer
memory when the VI runs. Also, not all operating systems and sound cards support
all sound format options.

• sample rate (S/s) —

sample rate (S/s) sets the sampling rate for the sound operation. Common rates are 44,100
S/s, 22,050 S/s, and 11,025 S/s. The default is 22,050 S/s.

• number of channels —

number of channels specifies the number of channels. This input can accept as many
channels as the sound card supports. For most sound cards 1 is Mono and 2 is Stereo.

• bits per sample —

2152 ni.com
 Functions

bits per sample specifies the quality of each sample in bits. Common resolutions are 16 bits
and 8 bits. The default is 16 bits.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID —

task ID returns an identification number associated with the configuration on the specified
device. You can pass task ID to other sound operation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Generate

Sound.vi
• labview\examples\Graphics and Sound\Sound\Sound File to
Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Start

Starts playback from the device. This VI is necessary only if the Sound Output Stop VI
has previously been called.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

© National Instruments 2153

 Functions

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Sound Output Write

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note If the buffer you set using the number of samples/ch input of the
Sound File Read VI is full when the application executes, LabVIEW
automatically implements a wait on the Sound Output Write VI even if you
set timeout to 0. This may cause the data flow to hang and return
unexpected results.

2154 ni.com
 Functions

• Sound Output Write (DBL) VI

• Sound Output Write (DBL Single) VI
• Sound Output Write (SGL) VI
• Sound Output Write (U8) VI
• Sound Output Write (I16) VI
• Sound Output Write (I32) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Write (DBL) VI

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note If the buffer you set using the number of samples/ch input of the
Sound File Read VI is full when the application executes, LabVIEW
automatically implements a wait on the Sound Output Write VI even if you
set timeout to 0. This may cause the data flow to hang and return
unexpected results.

© National Instruments 2155

 Functions

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the function waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely. If you set timeout (sec) to 0, the VI returns immediately while the sound
continues to play. You can use the Sound Output Wait VI to wait for playback to complete.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

2156 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Write (DBL Single) VI

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the
polymorphic instance you want to use.

Note The WFM instance of this VI writes data from a single waveform that
uses double-precision floating point numbers for the sound data.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• data —

data writes any sound data to the internal buffers.

© National Instruments 2157

 Functions

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the function waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely. If you set timeout (sec) to 0, the VI returns immediately while the sound
continues to play. You can use the Sound Output Wait VI to wait for playback to complete.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Write (SGL) VI

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the

2158 ni.com
 Functions

polymorphic instance you want to use.

Note Use the SGL instance to write data from a waveform that uses single-
precision floating point numbers for the sound data.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the function waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely. If you set timeout (sec) to 0, the VI returns immediately while the sound
continues to play. You can use the Sound Output Wait VI to wait for playback to complete.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

© National Instruments 2159

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Write (U8) VI

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note If the buffer you set using the number of samples/ch input of the
Sound File Read VI is full when the application executes, LabVIEW
automatically implements a wait on the Sound Output Write VI even if you
set timeout to 0. This may cause the data flow to hang and return
unexpected results.

2160 ni.com
 Functions

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the function waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely. If you set timeout (sec) to 0, the VI returns immediately while the sound
continues to play. You can use the Sound Output Wait VI to wait for playback to complete.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

© National Instruments 2161

 Functions

• labview\examples\Graphics and Sound\Sound\Generate

Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Write (I16) VI

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note If the buffer you set using the number of samples/ch input of the
Sound File Read VI is full when the application executes, LabVIEW
automatically implements a wait on the Sound Output Write VI even if you
set timeout to 0. This may cause the data flow to hang and return
unexpected results.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

2162 ni.com
 Functions

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the function waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely. If you set timeout (sec) to 0, the VI returns immediately while the sound
continues to play. You can use the Sound Output Wait VI to wait for playback to complete.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Write (I32) VI

Writes data to a sound output device. You must use the Sound Output Configure VI to
configure the device if you are writing continuously. You must manually select the

© National Instruments 2163

 Functions

polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note If the buffer you set using the number of samples/ch input of the
Sound File Read VI is full when the application executes, LabVIEW
automatically implements a wait on the Sound Output Write VI even if you
set timeout to 0. This may cause the data flow to hang and return
unexpected results.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the function waits for the sound operation to
complete.

2164 ni.com
 Functions

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely. If you set timeout (sec) to 0, the VI returns immediately while the sound
continues to play. You can use the Sound Output Wait VI to wait for playback to complete.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Stop

Stops the device from playing sound from the buffer. Use the Sound Output Clear VI to
clear the data in the buffer. Use the Sound Output Start VI to restart output.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• task ID —

© National Instruments 2165

 Functions

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Sound Output Clear

Stops the device from playing sound, clears the buffer, returns the task to the default
state, and clears the resources associated with the task. The task becomes invalid.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• error in (no error) —

2166 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Player.vi

• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Output Wait

Waits until all of the sound is played by the output device.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• error in (no error) —

© National Instruments 2167

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the VI waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound Output Info

Returns information about the current state of a sound output task.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

2168 ni.com
 Functions

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• is playing? —

is playing? indicates if the sound output task is playing.

• volume —

volume returns the volume of the sound operation, one value per channel. 0 is silent and 100 is
the loudest volume.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Player.vi

Sound Output Set Volume

Sets the volume at which the sound output device plays.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the

© National Instruments 2169

 Functions

Open Sound System (OSS) driver to use this VI.

Note Some Linux distributions use a version of the OSS sound driver that
does not support setting volume through the DSP device file. LabVIEW
cannot set the output volume on these distributions and returns a warning.

• Sound Output Set Volume (Single) VI

• Sound Output Set Volume (Array) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi

Sound Output Set Volume (Single) VI

Sets the volume at which the sound output device plays.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note Some Linux distributions use a version of the OSS sound driver that
does not support setting volume through the DSP device file. LabVIEW
cannot set the output volume on these distributions and returns a warning.

2170 ni.com
 Functions

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• volume —

volume specifies the volume of the sound operation. 0 is silent and 100 is the loudest volume.
The default is 100.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi

© National Instruments 2171

 Functions

Sound Output Set Volume (Array) VI

Sets the volume at which the sound output device plays.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Note Some Linux distributions use a version of the OSS sound driver that
does not support setting volume through the DSP device file. LabVIEW
cannot set the output volume on these distributions and returns a warning.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Output Configure VI.

• volume —

volume specifies the volume of the sound operation, one element per channel. 0 is silent and
100 is the loudest volume. The default is 100.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

2172 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Generate
Sound.vi

Play Sound File

Opens a file and starts playing it immediately.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• device ID —

device ID is the input or output device you access for a sound operation. In general, most users
should select the default value of 0.

The value ranges from 0 to n–1, where n is the number of input or output devices on the
computer.

• path —

path specifies the absolute path to the file from which you want to play sound data.

© National Instruments 2173

 Functions

If the path is empty or invalid, the VI returns an error. The default is <Not A Path>.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec)specifies the time, in seconds, that the VI waits for the sound operation to
complete.

The default is 0. This VI returns an error if the time elapses, unless timeout (sec) is 0. If you set
timeout (sec) to 0, this VI returns immediately while the sound continues to play. You can use
the Sound Output Wait VI to wait for playback to complete. If you set timeout (sec) to -1, this VI
waits until the sound finishes playing.

• task ID —

task ID returns an identification number associated with the configuration on the specified
device. You can pass task ID to other sound operation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Player.vi

Input

Use the Sound Input VIs to configure and control a sound input device.

(Windows) You must have DirectX 8.0 or later to use the Sound Input VIs.

(Linux) You must have the Open Sound System (OSS) driver to use this VI. LabVIEW
searches for input and output devices by looking for files named /dev/dsp or /dev/

2174 ni.com
 Functions

dspX, where X is an integer between 0 and 16. LabVIEW attempts to open each input
and output device. If LabVIEW cannot detect the sound card, check that a device file
named /dev/dsp or /dev/dspX exists on the local system and that you have
permission to read from and write to the device. If you moved this device to a location
other than the default, LabVIEW can work with a symbolic link.

Palette
Description
Object

Acquire Acquires data from a sound device. This Express VI automatically configures an input
Sound task, acquires the data, and clears the task after the acquisition completes.

Sound
Configures a sound input device to acquire data and send the data to the buffer. Use the
Input
Sound Input Read VI to read the data.
Configure

Sound
Starts data acquisition from the device. This VI is necessary only if Sound Input Stop has
Input
previously been called.
Start

Sound Reads data from a sound input device. You must use the Sound Input Configure VI to
Input configure the device. You must manually select the polymorphic instance you want to
Read use.

Sound Stops data acquisition from the device. Use the Sound Input Clear VI to clear the data in
Input the buffer. Use the Sound Input Start VI to restart the acquisition after calling the Sound
Stop Input Stop VI.

Sound
Stops acquisition of data, clears the buffer, returns the task to the default state, and
Input
clears the resources associated with the task. The task becomes invalid.
Clear

© National Instruments 2175

 Functions

Acquire Sound
Acquires data from a sound device. This Express VI automatically configures an input
task, acquires the data, and clears the task after the acquisition completes.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Dialog Box Options

Option Description

Device Lists the sound devices you have connected.

#Channels Specifies the number of channels. 1 is Mono, and 2 is Stereo.

Resolution (bits) Specifies the quality of each sample in bits. The default is 16 bits.

Duration (s) Sets the number of seconds for which you want to acquire sound.

Sample rate (Hz) Specifies the sample rate in hertz.

Preview Displays a preview of the sound operation in the graph.

2176 ni.com
 Functions

Option Description

Graph Preview Displays a preview of the sound operation.

Inputs/Outputs
• Device —

Lists the sound devices you have connected.

• Sample rate (Hz) —

Specifies the sample rate in hertz.

• Resolution (bits) —

Specifies the quality of each sample in bits. The default is 16 bits.

• error in (no error) —

Describes error conditions that occur before this node runs.

• Duration (s) —

Sets the number of seconds for which you want to acquire sound.

• #Channels —

Specifies the number of channels. 1 is Mono, and 2 is Stereo.

• Data —

Returns the data this Express VI acquires from the selected device using the settings you specify
in the configuration dialog box.

You can convert this output to a waveform or one-dimensional array of waveforms (one per
channel) by using the Convert from Dynamic Data function.

• error out —

Contains error information. This output provides standard error out functionality.

© National Instruments 2177

 Functions

Components

Specifies the quality of each sample in bits. The default is 16 bits.

Lists the sound devices you have connected.

Sets the number of seconds for which you want to acquire sound.

Specifies the number of channels. 1 is Mono, and 2 is Stereo.

Displays a preview of the sound operation in the graph.

Specifies the sample rate in hertz.

Displays a preview of the sound operation.

Sound Input Configure

Configures a sound input device to acquire data and send the data to the buffer. Use
the Sound Input Read VI to read the data.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel in the buffer.

Use a large number of samples for continuous operations. Use a smaller number of samples if
you want to use less memory.

• sample mode —

2178 ni.com
 Functions

sample mode specifies whether the VI acquires samples just once (Finite Samples) or
continuously (Continuous Samples).

In Finite Samples mode, call Sound Input Read only until you have written the number of
samples specified in number of samples/ch. In Continuous Samples mode, you can call Sound
Input Read repeatedly as needed.

• device ID —

device ID is the input or output device you access for a sound operation. In general, most users
should select the default value of 0.

The value ranges from 0 to n–1, where n is the number of input or output devices on the
computer.

• sound format —

sound format sets the acquisition rate, the number of channels, and the bits per sample of the
sound operation. The values for each of these controls is dependent on your sound card.

Note Setting sample rate (S/s) and bits per sample high uses more of the computer
memory when the VI runs. Also, not all operating systems and sound cards support
all sound format options.

• sample rate (S/s) —

sample rate (S/s) sets the sampling rate for the sound operation. Common rates are 44,100
S/s, 22,050 S/s, and 11,025 S/s. The default is 22,050 S/s.

• number of channels —

number of channels specifies the number of channels. This input can accept as many
channels as the sound card supports. For most sound cards 1 is Mono and 2 is Stereo.

• bits per sample —

bits per sample specifies the quality of each sample in bits. Common resolutions are 16 bits
and 8 bits. The default is 16 bits.

• error in (no error) —

© National Instruments 2179

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID —

task ID returns an identification number associated with the configuration on the specified
device. You can pass task ID to other sound operation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Input Start

Starts data acquisition from the device. This VI is necessary only if Sound Input Stop
has previously been called.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• task ID —

2180 ni.com
 Functions

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Sound Input Read

Reads data from a sound input device. You must use the Sound Input Configure VI to
configure the device. You must manually select the polymorphic instance you want to
use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

• Sound Input Read (DBL) VI

• Sound Input Read (SGL) VI
• Sound Input Read (U8) VI
• Sound Input Read (I16) VI
• Sound Input Read (I32) VI

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2181

 Functions

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Input Read (DBL) VI

Reads data from a sound input device. You must use the Sound Input Configure VI to
configure the device. You must manually select the polymorphic instance you want to
use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel to read from the buffer.

• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

2182 ni.com
 Functions

timeout (sec) specifies the time, in seconds, that the VI waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• data —

data reads any sound data from the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Input Read (SGL) VI

Reads data from a sound input device. You must use the Sound Input Configure VI to
configure the device. You must manually select the polymorphic instance you want to
use.

© National Instruments 2183

 Functions

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel to read from the buffer.

• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the VI waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• data —

data reads any sound data from the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

2184 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Input Read (U8) VI

Reads data from a sound input device. You must use the Sound Input Configure VI to
configure the device. You must manually select the polymorphic instance you want to
use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel to read from the buffer.

• task ID —

© National Instruments 2185

 Functions

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the VI waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• data —

data reads any sound data from the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous

2186 ni.com
 Functions

Sound Input Output.vi

Sound Input Read (I16) VI

Reads data from a sound input device. You must use the Sound Input Configure VI to
configure the device. You must manually select the polymorphic instance you want to
use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel to read from the buffer.

• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the VI waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely.

© National Instruments 2187

 Functions

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• data —

data reads any sound data from the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Input Read (I32) VI

Reads data from a sound input device. You must use the Sound Input Configure VI to
configure the device. You must manually select the polymorphic instance you want to
use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

2188 ni.com
 Functions

Inputs/Outputs
• number of samples/ch —

number of samples/ch specifies the number of samples per channel to read from the buffer.

• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• timeout (sec) —

timeout (sec) specifies the time, in seconds, that the VI waits for the sound operation to
complete.

This VI returns an error if the time elapses. The default is 10. If you set timeout (sec) to -1, the VI
waits indefinitely.

• task ID out —

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• data —

data reads any sound data from the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2189

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Continuous

Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Finite Sound
Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Sound Input Stop

Stops data acquisition from the device. Use the Sound Input Clear VI to clear the data
in the buffer. Use the Sound Input Start VI to restart the acquisition after calling the
Sound Input Stop VI.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• task ID out —

2190 ni.com
 Functions

task ID out is the manipulated sound operation originally passed to the task ID parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Sound Input Clear

Stops acquisition of data, clears the buffer, returns the task to the default state, and
clears the resources associated with the task. The task becomes invalid.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• task ID —

task ID is the sound operation from the configured device you want to manipulate or input.

You generate task ID with the Sound Input Configure VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2191

 Functions

• labview\examples\Graphics and Sound\Sound\Finite Sound

Input.vi
• labview\examples\Graphics and Sound\Sound\Continuous
Sound Input.vi
• labview\examples\Graphics and Sound\Sound\Simultaneous
Sound Input Output.vi

Files

Use the Sound Files VIs to create and retrieve PC wave files (.wav).

(Windows) You must have DirectX 8.0 or later to use the Sound File VIs.

(Linux) You must have the Open Sound System (OSS) driver to use this VI. LabVIEW
searches for input and output devices by looking for files named /dev/dsp or /dev/
dspX, where X is an integer between 0 and 16. LabVIEW attempts to open each input
and output device. If LabVIEW cannot detect the sound card, check that a device file
named /dev/dsp or /dev/dspX exists on the local system and that you have
permission to read from and write to the device. If you moved this device to a location
other than the default, LabVIEW can work with a symbolic link.

Palette
Description
Object

Sound File Reads data from a .wav file into an array of waveforms. This VI automatically
Read Simple opens, reads, and closes the .wav file.

Sound File Writes data from an array of waveforms to a .wav file. This VI automatically opens,
Write Simple writes to, and closes the .wav file.

Sound File Opens a .wav file for reading or creates a new .wav file for writing. You must
Open manually select the polymorphic instance you want to use.

2192 ni.com
 Functions

Palette
Description
Object

Sound File
Retrieves data about a .wav file. This VI accepts either a path or a refnum.
Info

Sound File Reads data from a .wav file into an array of waveforms. You must manually select
Read the polymorphic instance you want to use.

Sound File
Writes data from a waveform or an array of waveforms to a .wav file.
Write

Sound File
Closes a .wav file.
Close

Sound File Read Simple

Reads data from a .wav file into an array of waveforms. This VI automatically opens,
reads, and closes the .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files.

Inputs/Outputs
• number of samples/ch (-1: all) —

number of samples/ch specifies the number of samples per channel to read from the file. -1
specifies all samples.

© National Instruments 2193

 Functions

• path —

path specifies the absolute path to the wave file.

If the path is empty or invalid, the VI returns an error. The default is <Not A Path>.

• position mode —

position mode, together with position offset, specifies where the read operation begins.

Absolute starts the operation at the beginning of the file plus position offset, so the offset is
relative to the beginning of the file. Relative starts the operation at the current location of the
file mark plus position offset. The default is Relative.

• position offset —

position offset specifies how far from the location specified by position mode to start reading.

You express position offset in units of samples. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

path out identifies the wave file passed in path.

• data —

data reads any sound data from the file. For multi-channel sound data, data is an array of
waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• offset —

offset indicates the new location of the file mark relative to the beginning of the file, in units of
samples.

The default is 0.

• error out —

2194 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Read Sound File

to Graph.vi

Sound File Write Simple

Writes data from an array of waveforms to a .wav file. This VI automatically opens,
writes to, and closes the .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• path —

path specifies the absolute path to the wave file.

If the path is empty or invalid, the VI returns an error. The default is <Not A Path>.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• bits per sample —

© National Instruments 2195

 Functions

bits per sample specifies the quality of each sample in bits. Common resolutions are 16 bits and
8 bits. The default is 16 bits.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

path out identifies the wave file passed in path.

• error out —

error out contains error information. This output provides standard error out functionality.

Sound File Open

Opens a .wav file for reading or creates a new .wav file for writing. You must
manually select the polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

• Sound File Read Open VI

• Sound File Write Open VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Sound Input to

2196 ni.com
 Functions

File.vi

Sound File Read Open VI

Opens a .wav file for reading or creates a new .wav file for writing. You must
manually select the polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• path —

path specifies the absolute path to the wave file.

If the path is empty or invalid, the VI returns an error. The default is <Not A Path>.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum —

sound file refnum returns a reference to the sound file. You can pass sound file refnum to other
Sound Files VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2197

 Functions

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Sound Input to
File.vi

Sound File Write Open VI

Opens a .wav file for reading or creates a new .wav file for writing. You must
manually select the polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• path —

path specifies the absolute path to the wave file.

If the path is empty or invalid, the VI returns an error. The default is <Not A Path>.

• sound format —

sound format sets the sample rate, the number of channels, and the bits per sample for the
wave file. The values for each of these controls is dependent on your sound card.

• sample rate (S/s) —

sample rate (S/s) sets the sampling rate for the wave file. Common rates are 44,100 S/s,
22,050 S/s, and 11,025 S/s. The default is 22050 S/s.

• number of channels —

number of channels specifies the number of channels. This input can accept as many

2198 ni.com
 Functions

channels as the sound card supports. For most sound cards 1 is Mono and 2 is Stereo.

• bits per sample —

bits per sample specifies the quality of each sample in bits. Common resolutions are 16 bits
and 8 bits. The default is 16 bits.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum —

sound file refnum returns a reference to the sound file. You can pass sound file refnum to other
Sound Files VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi
• labview\examples\Graphics and Sound\Sound\Sound Input to
File.vi

Sound File Info

Retrieves data about a .wav file. This VI accepts either a path or a refnum.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

© National Instruments 2199

 Functions

• Sound File Info (path) VI

• Sound File Info (refnum) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Info (path) VI

Retrieves data about a .wav file. This VI accepts either a path or a refnum.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• path —

path specifies the absolute path to the wave file.

If the path is empty or invalid, the VI returns an error. The default is <Not A Path>.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

2200 ni.com
 Functions

path out identifies the wave file passed in path.

• total number of samples/ch —

total number of samples/ch returns the total number of samples per channel in the wave file.

• sound format —

sound format returns the sample rate, the number of channels, and the number of bits per
sample in the wave file.

• sample rate (S/s) —

sample rate (S/s) is the sampling rate for the wave file. Common rates are 44,100 S/s, 22,050
S/s, and 11,025 S/s.

• number of channels —

number of channels specifies the number of channels in the wave file. This input can
accept as many channels as the sound card supports. For most sound cards 1 is Mono and 2
is Stereo.

• bits per sample —

bits per sample is the quality of each sample in bits. Common resolutions are 16 bits and 8
bits.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

© National Instruments 2201

 Functions

Sound File Info (refnum) VI

Retrieves data about a .wav file. This VI accepts either a path or a refnum.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• total number of samples/ch —

total number of samples/ch returns the total number of samples per channel in the wave file.

• sound format —

sound format returns the sample rate, the number of channels, and the number of bits per
sample in the wave file.

• sample rate (S/s) —

2202 ni.com
 Functions

sample rate (S/s) is the sampling rate for the wave file. Common rates are 44,100 S/s, 22,050
S/s, and 11,025 S/s.

• number of channels —

number of channels specifies the number of channels in the wave file. This input can
accept as many channels as the sound card supports. For most sound cards 1 is Mono and 2
is Stereo.

• bits per sample —

bits per sample is the quality of each sample in bits. Common resolutions are 16 bits and 8
bits.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Read

Reads data from a .wav file into an array of waveforms. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files. LabVIEW uses large
amounts of memory when reading an entire wave file at once. Instead, read
wave files in chunks.

© National Instruments 2203

 Functions

• Sound File Read (DBL) VI

• Sound File Read (SGL) VI
• Sound File Read (U8) VI
• Sound File Read (I16) VI
• Sound File Read (I32) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Read (DBL) VI

Reads data from a .wav file into an array of waveforms. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files. LabVIEW uses large
amounts of memory when reading an entire wave file at once. Instead, read
wave files in chunks.

Inputs/Outputs
• number of samples/ch (-1: all) —

2204 ni.com
 Functions

number of samples/ch specifies the number of samples per channel to read from the file. -1
specifies all samples.

• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• position mode —

position mode, together with position offset, specifies where the read operation begins.

Absolute starts the operation at the beginning of the file plus position offset, so the offset is
relative to the beginning of the file. Relative starts the operation at the current location of the
file mark plus position offset. The default is Relative.

• position offset —

position offset specifies how far from the location specified by position mode to start reading.

You express position offset in units of samples. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• data —

data reads any sound data from the file. For multi-channel sound data, data is an array of
waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• offset —

offset indicates the new location of the file mark relative to the beginning of the file, in units of
samples.

© National Instruments 2205

 Functions

The default is 0.

• error out —

error out contains error information. This output provides standard error out functionality.

• end of file? —

end of file? returns TRUE when the VI reaches the end of the file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Read (SGL) VI

Reads data from a .wav file into an array of waveforms. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files. LabVIEW uses large
amounts of memory when reading an entire wave file at once. Instead, read
wave files in chunks.

2206 ni.com
 Functions

Inputs/Outputs
• number of samples/ch (-1: all) —

number of samples/ch specifies the number of samples per channel to read from the file. -1
specifies all samples.

• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• position mode —

position mode, together with position offset, specifies where the read operation begins.

Absolute starts the operation at the beginning of the file plus position offset, so the offset is
relative to the beginning of the file. Relative starts the operation at the current location of the
file mark plus position offset. The default is Relative.

• position offset —

position offset specifies how far from the location specified by position mode to start reading.

You express position offset in units of samples. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• data —

data reads any sound data from the file. For multi-channel sound data, data is an array of
waveforms where each element of the array is a single channel.

• offset —

offset indicates the new location of the file mark relative to the beginning of the file, in units of

© National Instruments 2207

 Functions

samples.

The default is 0.

• error out —

error out contains error information. This output provides standard error out functionality.

• end of file? —

end of file? returns TRUE when the VI reaches the end of the file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Read (U8) VI

Reads data from a .wav file into an array of waveforms. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files. LabVIEW uses large
amounts of memory when reading an entire wave file at once. Instead, read
wave files in chunks.

2208 ni.com
 Functions

Inputs/Outputs
• number of samples/ch (-1: all) —

number of samples/ch specifies the number of samples per channel to read from the file. -1
specifies all samples.

• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• position mode —

position mode, together with position offset, specifies where the read operation begins.

Absolute starts the operation at the beginning of the file plus position offset, so the offset is
relative to the beginning of the file. Relative starts the operation at the current location of the
file mark plus position offset. The default is Relative.

• position offset —

position offset specifies how far from the location specified by position mode to start reading.

You express position offset in units of samples. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• data —

data reads any sound data from the file. For multi-channel sound data, data is an array of
waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• offset —

© National Instruments 2209

 Functions

offset indicates the new location of the file mark relative to the beginning of the file, in units of
samples.

The default is 0.

• error out —

error out contains error information. This output provides standard error out functionality.

• end of file? —

end of file? returns TRUE when the VI reaches the end of the file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Read (I16) VI

Reads data from a .wav file into an array of waveforms. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files. LabVIEW uses large
amounts of memory when reading an entire wave file at once. Instead, read
wave files in chunks.

2210 ni.com
 Functions

Inputs/Outputs
• number of samples/ch (-1: all) —

number of samples/ch specifies the number of samples per channel to read from the file. -1
specifies all samples.

• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• position mode —

position mode, together with position offset, specifies where the read operation begins.

Absolute starts the operation at the beginning of the file plus position offset, so the offset is
relative to the beginning of the file. Relative starts the operation at the current location of the
file mark plus position offset. The default is Relative.

• position offset —

position offset specifies how far from the location specified by position mode to start reading.

You express position offset in units of samples. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• data —

data reads any sound data from the file. For multi-channel sound data, data is an array of
waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• offset —

© National Instruments 2211

 Functions

offset indicates the new location of the file mark relative to the beginning of the file, in units of
samples.

The default is 0.

• error out —

error out contains error information. This output provides standard error out functionality.

• end of file? —

end of file? returns TRUE when the VI reaches the end of the file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Read (I32) VI

Reads data from a .wav file into an array of waveforms. You must manually select the
polymorphic instance you want to use.

(Windows) You must have DirectX 8.0 or later to use this VI.

Note This VI retrieves only uncompressed wave files. LabVIEW uses large
amounts of memory when reading an entire wave file at once. Instead, read
wave files in chunks.

2212 ni.com
 Functions

Inputs/Outputs
• number of samples/ch (-1: all) —

number of samples/ch specifies the number of samples per channel to read from the file. -1
specifies all samples.

• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• position mode —

position mode, together with position offset, specifies where the read operation begins.

Absolute starts the operation at the beginning of the file plus position offset, so the offset is
relative to the beginning of the file. Relative starts the operation at the current location of the
file mark plus position offset. The default is Relative.

• position offset —

position offset specifies how far from the location specified by position mode to start reading.

You express position offset in units of samples. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• data —

data reads any sound data from the file. For multi-channel sound data, data is an array of
waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• offset —

© National Instruments 2213

 Functions

offset indicates the new location of the file mark relative to the beginning of the file, in units of
samples.

The default is 0.

• error out —

error out contains error information. This output provides standard error out functionality.

• end of file? —

end of file? returns TRUE when the VI reaches the end of the file.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound File to

Sound Output.vi

Sound File Write

Writes data from a waveform or an array of waveforms to a .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

• Sound File Write (DBL) VI

• Sound File Write (DBL Single) VI
• Sound File Write (SGL) VI
• Sound File Write (U8) VI
• Sound File Write (I16) VI
• Sound File Write (I32) VI

2214 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

Sound File Write (DBL) VI

Writes data from a waveform or an array of waveforms to a .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

© National Instruments 2215

 Functions

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

Sound File Write (DBL Single) VI

Writes data from a waveform or an array of waveforms to a .wav file.

Note The WFM instance of this VI writes data from a single waveform that
uses double-precision floating point numbers for the sound data.

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• data —

data writes any sound data to the internal buffers.

2216 ni.com
 Functions

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

Sound File Write (SGL) VI

Writes data from a waveform or an array of waveforms to a .wav file.

Note Use the SGL instance to write data from a waveform that uses single-
precision floating point numbers for the sound data.

Inputs/Outputs
• sound file refnum —

© National Instruments 2217

 Functions

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

Sound File Write (U8) VI

Writes data from a waveform or an array of waveforms to a .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

2218 ni.com
 Functions

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

© National Instruments 2219

 Functions

Sound File Write (I16) VI

Writes data from a waveform or an array of waveforms to a .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

2220 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

Sound File Write (I32) VI

Writes data from a waveform or an array of waveforms to a .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• data —

data writes any sound data to the internal buffers. For multi-channel sound data, data is an
array of waveforms where each element of the array is a single channel.

The specified data type determines the range of values for the sound data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• sound file refnum out —

© National Instruments 2221

 Functions

sound file refnum out is the reference to the sound file originally passed in the sound file
refnum parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi

Sound File Close

Closes a .wav file.

(Windows) You must have DirectX 8.0 or later to use this VI. (Linux) You must have the
Open Sound System (OSS) driver to use this VI.

Inputs/Outputs
• sound file refnum —

sound file refnum is the reference to the sound file.

You generate sound file refnum with the Sound File Open VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

2222 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\Sound\Sound Input to

File.vi
• labview\examples\Graphics and Sound\Sound\Sound File to
Sound Output.vi

Math Plot Helpers

This section contains reference information for 2D and 3D Math Plots.

The following VIs appear on the block diagram when you add the associated plot to
the front panel. You can find plots on the 2D Graph and 3D Graph palette.

2D Compass Plot Helper

Graphs vectors that emanate from the center origin in a compass plot. Multiple
references to this VI generate multiple plots on the same graph.

Note This VI appears on the block diagram when you add a Compass Plot to
the front panel. You can find the Compass Plot on the Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Complex) VI

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2223

 Functions

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Compass Plot.vi

Plot Helper (Vector) VI

Graphs vectors that emanate from the center origin in a compass plot. Multiple
references to this VI generate multiple plots on the same graph.

Note This VI appears on the block diagram when you add a Compass Plot to
the front panel. You can find the Compass Plot on the Graph palette.

Inputs/Outputs
• 2D Plot Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the 2D plot.

• theta vector —

theta vector specifies the angles on the compass plot you want to graph.

• radius vector —

radius vector specifies the vector length as it extends from the center.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 2D Plot Class Obj Array out —

2D Plot Class Obj Array out is the graph of the 2D plot.

• error out —

2224 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Compass Plot.vi

Plot Helper (Complex) VI

Graphs vectors that emanate from the center origin in a compass plot. Multiple
references to this VI generate multiple plots on the same graph.

Note This VI appears on the block diagram when you add a Compass Plot to
the front panel. You can find the Compass Plot on the Graph palette.

Inputs/Outputs
• 2D Plot Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the 2D plot.

• z vector —

z vector specifies a vector of complex numbers.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 2D Plot Class Obj Array out —

© National Instruments 2225

 Functions

2D Plot Class Obj Array out is the graph of the 2D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Compass Plot.vi

2D Error Bar Plot Helper

Graphs a plot that displays the percentage or vector of error at each point above and
below the line graph. Multiple references to this VI generate multiple plots on the same
graph.

Note This VI appears on the block diagram when you add a Error Bar Plot to
the front panel. You can find the Error Bar Plot on the Graph palette.

• Plot Helper (Percentage) VI

• Plot Helper (Fixed) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Error Bar Plot.vi

2226 ni.com
 Functions

Plot Helper (Percentage) VI

Graphs a plot that displays the percentage or vector of error at each point above and
below the line graph. Multiple references to this VI generate multiple plots on the same
graph.

Note This VI appears on the block diagram when you add a Error Bar Plot to
the front panel. You can find the Error Bar Plot on the Graph palette.

Inputs/Outputs
• error b percentage —

error b percentage specifies the percentage of error that appears at each point below the
graphed line relative to values you specify in y vector.

• error a percentage —

error a percentage specifies the percentage of error that appears at each point above the
graphed line relative to values you specify in y vector.

• 2D Plot Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the 2D plot.

• x vector —

x vector specifies the x-coordinates you want to plot.

• y vector —

y vector specifies the y-coordinates you want to plot.

• error in (no error) —

© National Instruments 2227

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 2D Plot Class Obj Array out —

2D Plot Class Obj Array out is the graph of the error bar plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Error Bar Plot.vi

Plot Helper (Fixed) VI

Graphs a plot that displays the percentage or vector of error at each point above and
below the line graph. Multiple references to this VI generate multiple plots on the same
graph.

Note This VI appears on the block diagram when you add a Error Bar Plot to
the front panel. You can find the Error Bar Plot on the Graph palette.

Inputs/Outputs
• error b vector —

2228 ni.com
 Functions

error b vector specifies the vector of error that appears at each point below the graphed line
relative to values you specify in y vector.

• error a vector —

error a vector specifies the vector of error that appears at each point above the graphed line
relative to values you specify in y vector.

• 2D Plot Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the 2D plot.

• x vector —

x vector specifies the x-coordinates you want to plot.

• y vector —

y vector specifies the y-coordinates you want to plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 2D Plot Class Obj Array out —

2D Plot Class Obj Array out is the graph of the error bar plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Error Bar Plot.vi

© National Instruments 2229

 Functions

2D Feather Plot Helper

Graphs vectors that emanate from equally spaced points along a horizontal axis at
zero. Multiple references to this VI generate multiple plots on the same graph.

Note This VI appears on the block diagram when you add a Feather Plot to
the front panel. You can find the Feather Plot on the Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Complex) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Feather Plot.vi

Plot Helper (Vector) VI

Graphs vectors that emanate from equally spaced points along a horizontal axis at
zero. Multiple references to this VI generate multiple plots on the same graph.

Note This VI appears on the block diagram when you add a Feather Plot to
the front panel. You can find the Feather Plot on the Graph palette.

2230 ni.com
 Functions

Inputs/Outputs
• 2D Plot Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the 2D plot.

• x vector —

x vector specifies the x-coordinates for the end points of the vectors that emanate from the
horizontal axis.

• y vector —

y vector specifies the y-coordinates for the length of the vectors that emanate from the
horizontal axis.

• error in (no error) —

The error in cluster can accept error information wired from VIs previously called. Use this
information to decide if any functionality should be bypassed in the event of errors from other
VIs. The pop-up option Explain Error (or Explain Warning) gives more information about the
error displayed.

• 2D Plot Class Obj Array out —

2D Plot Class Obj Array out is the graph of the feather plot.

• error out —

error out passes error or warning information out of a VI to be used by other VIs. Right-click the
error out indicator on the front panel and select Explain Error or Explain Warning from the
shortcut menu for more information about the error.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Feather Plot.vi

© National Instruments 2231

 Functions

Plot Helper (Complex) VI

Graphs vectors that emanate from equally spaced points along a horizontal axis at
zero. Multiple references to this VI generate multiple plots on the same graph.

Note This VI appears on the block diagram when you add a Feather Plot to
the front panel. You can find the Feather Plot on the Graph palette.

Inputs/Outputs
• 2D Plot Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the 2D plot.

• z vector —

z vector specifies a vector of complex numbers.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 2D Plot Class Obj Array out —

2D Plot Class Obj Array out is the graph of the feather plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

2232 ni.com
 Functions

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\Feather Plot.vi

3D Bar Plot Helper

Generates a plot of vertical bars.

Note This VI appears on the block diagram when you add a Bar plot to the
front panel. You can find the Bar plot on the 3D Graph palette.

• Plot Helper (Matrix) VI

• Plot Helper (Vector) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Bar Graph.vi

Plot Helper (Matrix) VI

Generates a plot of vertical bars.

Note This VI appears on the block diagram when you add a Bar plot to the
front panel. You can find the Bar plot on the 3D Graph palette.

© National Instruments 2233

 Functions

Inputs/Outputs
• y vector —

y vector is a 1D array that specifies the y-coordinates of the bars you want to plot. If you wire y
vector the length of y vector must equal the length of z matrix.

• z matrix —

z matrix is a 2D array that specifies the heights of the bars you graph.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Bar Graph.vi

Plot Helper (Vector) VI

Generates a plot of vertical bars.

Note This VI appears on the block diagram when you add a Bar plot to the
front panel. You can find the Bar plot on the 3D Graph palette.

2234 ni.com
 Functions

Inputs/Outputs
• y vector —

y vector is a 1D array that specifies the y-coordinates of the bars you want to plot. If you wire y
vector, the length of y vector must equal the length of z vector.

• z vector —

z vector is a 1D array that specifies the heights of the bars you want to plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Bar Graph.vi

3D Comet Plot Helper

Creates an animated graph with a circle that follows the data points. Multiple
references to this VI generate multiple plots for the same graph.

© National Instruments 2235

 Functions

Note This VI appears on the block diagram when you add a Comet plot to
the front panel. You can find the Comet plot on the 3D Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI
• Plot Helper (Matrices) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Comet Graph.vi

Plot Helper (Vector) VI

Creates an animated graph with a circle that follows the data points. Multiple
references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Comet plot to
the front panel. You can find the Comet plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

2236 ni.com
 Functions

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z vector —

z vector is a 1D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Comet Graph.vi

© National Instruments 2237

 Functions

Plot Helper (Matrix) VI

Creates an animated graph with a circle that follows the data points. Multiple
references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Comet plot to
the front panel. You can find the Comet plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

2238 ni.com
 Functions

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Comet Graph.vi

Plot Helper (Matrices) VI

Creates an animated graph with a circle that follows the data points. Multiple
references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Comet plot to
the front panel. You can find the Comet plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

© National Instruments 2239

 Functions

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Comet Graph.vi

2240 ni.com
 Functions

3D Contour Plot Helper

Graphs a plot with contour lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Contour plot to
the front panel. You can find the Contour plot on the 3D Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI

When x matrix, y matrix, and z matrix are the same size, the Contour plot graphs
values that correspond to each element at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Contour Graph.vi

Plot Helper (Vector) VI

Graphs a plot with contour lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Contour plot to
the front panel. You can find the Contour plot on the 3D Graph palette.

© National Instruments 2241

 Functions

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

When x matrix, y matrix, and z matrix are the same size, the Contour plot graphs

2242 ni.com
 Functions

values that correspond to each element at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Contour Graph.vi

Plot Helper (Matrix) VI

Graphs a plot with contour lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Contour plot to
the front panel. You can find the Contour plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

© National Instruments 2243

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

When x matrix, y matrix, and z matrix are the same size, the Contour plot graphs
values that correspond to each element at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Contour Graph.vi

3D Mesh Plot Helper

Graphs a mesh surface with open spaces. Multiple references to this VI generate
multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Mesh plot to the
front panel. You can find the Mesh plot on the 3D Graph palette.

2244 ni.com
 Functions

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI

When x matrix, y matrix, and z matrix are the same size, the Mesh plot graphs values
that correspond to each elements at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Mesh Graph.vi

Plot Helper (Vector) VI

Graphs a mesh surface with open spaces. Multiple references to this VI generate
multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Mesh plot to the
front panel. You can find the Mesh plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

© National Instruments 2245

 Functions

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

When x matrix, y matrix, and z matrix are the same size, the Mesh plot graphs values
that correspond to each elements at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Mesh Graph.vi

2246 ni.com
 Functions

Plot Helper (Matrix) VI

Graphs a mesh surface with open spaces. Multiple references to this VI generate
multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Mesh plot to the
front panel. You can find the Mesh plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

© National Instruments 2247

 Functions

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

When x matrix, y matrix, and z matrix are the same size, the Mesh plot graphs values
that correspond to each elements at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Mesh Graph.vi

3D Pie Plot Helper

Generates a pie chart.

Note This VI appears on the block diagram when you add a Pie plot to the
front panel. You can find the Pie plot on the 3D Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI

2248 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Pie Graph.vi

Plot Helper (Vector) VI

Generates a pie chart.

Note This VI appears on the block diagram when you add a Pie plot to the
front panel. You can find the Pie plot on the 3D Graph palette.

Inputs/Outputs
• x vector —

x vector is a 1D array that specifies the size of the slices, or percentages of pie, that appear in the
graph. LabVIEW ignores the non-positive elements in x vector.

• offset vector —

offset vector specifies how far slices of pie offset from the center point if they offset. The length
of offset vector must equal the length of x vector.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

© National Instruments 2249

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Pie Graph.vi

Plot Helper (Matrix) VI

Generates a pie chart.

Note This VI appears on the block diagram when you add a Pie plot to the
front panel. You can find the Pie plot on the 3D Graph palette.

Inputs/Outputs
• x matrix —

x matrix is a 2D array that specifies the size of the slices, or percentages of pie, that appear in the
graph. LabVIEW ignores the non-positive elements in x matrix.

• offset matrix —

offset matrix specifies how far slices of pie offset from the center point if they offset. The length
of offset matrix must equal the length of x matrix.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

2250 ni.com
 Functions

standard error in functionality.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Pie Graph.vi

3D Quiver Plot Helper

Graphs a plot of normal vectors. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Quiver plot to
the front panel. You can find the Quiver plot on the 3D Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

© National Instruments 2251

 Functions

Charts\Math Plots - 3D\3D Quiver Graph.vi

Plot Helper (Vector) VI

Graphs a plot of normal vectors. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Quiver plot to
the front panel. You can find the Quiver plot on the 3D Graph palette.

Inputs/Outputs
• Nz matrix —

Nz matrix is a 2D array that specifies the length of the z vector in relation to the z-plane.

• Ny matrix —

Ny matrix is a 2D array that specifies the length of the y vector in relation to the z-plane.

• Nx matrix —

Nx matrix is a 2D array that specifies the length of the x vector in relation to the z-plane.

• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

2252 ni.com
 Functions

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Quiver Graph.vi

Plot Helper (Matrix) VI

Graphs a plot of normal vectors. Multiple references to this VI generate multiple plots
for the same graph.

© National Instruments 2253

 Functions

Note This VI appears on the block diagram when you add a Quiver plot to
the front panel. You can find the Quiver plot on the 3D Graph palette.

Inputs/Outputs
• Nz matrix —

Nz matrix is a 2D array that specifies the length of the z vector in relation to the z-plane.

• Ny matrix —

Ny matrix is a 2D array that specifies the length of the y vector in relation to the z-plane.

• Nx matrix —

Nx matrix is a 2D array that specifies the length of the x vector in relation to the z-plane.

• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• error in (no error) —

2254 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Quiver Graph.vi

3D Ribbon Plot Helper

Generates a plot of parallel lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Ribbon plot to
the front panel. You can find the Ribbon plot on the 3D Graph palette.

• Plot Helper (Standard) VI

• Plot Helper (Vector) VI

© National Instruments 2255

 Functions

• Plot Helper (Matrix) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Ribbon Graph.vi

Plot Helper (Standard) VI

Generates a plot of parallel lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Ribbon plot to
the front panel. You can find the Ribbon plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

2256 ni.com
 Functions

z matrix is a 2D array that specifies the z-coordinates that graph the plot. A ribbon generates for
each row in z matrix.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Ribbon Graph.vi

Plot Helper (Vector) VI

Generates a plot of parallel lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Ribbon plot to
the front panel. You can find the Ribbon plot on the 3D Graph palette.

© National Instruments 2257

 Functions

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot. A ribbon generates for
each row in z matrix.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

2258 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Ribbon Graph.vi

Plot Helper (Matrix) VI

Generates a plot of parallel lines. Multiple references to this VI generate multiple plots
for the same graph.

Note This VI appears on the block diagram when you add a Ribbon plot to
the front panel. You can find the Ribbon plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

© National Instruments 2259

 Functions

standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot. A ribbon generates for
each row in z matrix.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Ribbon Graph.vi

3D Scatter Plot Helper

Graphs data to show trends in statistics and the relationship between two sets of data.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Scatter plot to
the front panel. You can find the Scatter plot on the 3D Graph palette.

2260 ni.com
 Functions

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI
• Plot Helper (Matrices) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Scatter Graph.vi

Plot Helper (Vector) VI

Graphs data to show trends in statistics and the relationship between two sets of data.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Scatter plot to
the front panel. You can find the Scatter plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

© National Instruments 2261

 Functions

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z vector —

z vector is a 1D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Scatter Graph.vi

Plot Helper (Matrix) VI

Graphs data to show trends in statistics and the relationship between two sets of data.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Scatter plot to

2262 ni.com
 Functions

the front panel. You can find the Scatter plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

© National Instruments 2263

 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Scatter Graph.vi

Plot Helper (Matrices) VI

Graphs data to show trends in statistics and the relationship between two sets of data.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Scatter plot to
the front panel. You can find the Scatter plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

2264 ni.com
 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Scatter Graph.vi

3D Stem Plot Helper

Displays an impulse response and organizes data by its distribution at 0 on the z-plane.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Stem plot to the
front panel. You can find the Stem plot on the 3D Graph palette.

© National Instruments 2265

 Functions

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI
• Plot Helper (Matrices) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Stem Graph.vi

Plot Helper (Vector) VI

Displays an impulse response and organizes data by its distribution at 0 on the z-plane.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Stem plot to the
front panel. You can find the Stem plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

2266 ni.com
 Functions

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z vector —

z vector is a 1D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Stem Graph.vi

Plot Helper (Matrix) VI

Displays an impulse response and organizes data by its distribution at 0 on the z-plane.
Multiple references to this VI generate multiple plots for the same graph.

© National Instruments 2267

 Functions

Note This VI appears on the block diagram when you add a Stem plot to the
front panel. You can find the Stem plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

2268 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Stem Graph.vi

Plot Helper (Matrices) VI

Displays an impulse response and organizes data by its distribution at 0 on the z-plane.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Stem plot to the
front panel. You can find the Stem plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

© National Instruments 2269

 Functions

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Stem Graph.vi

3D Surface Plot Helper

Graphs data with a connecting surface. Multiple references to this VI generate multiple
plots for the same graph.

Note This VI appears on the block diagram when you add a Surface plot to
the front panel. You can find the Surface plot on the 3D Graph palette.

2270 ni.com
 Functions

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI

When x matrix, y matrix, and z matrix are the same size, the Surface plot graphs
values that correspond to each elements at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Surface Graph.vi

Plot Helper (Vector) VI

Graphs data with a connecting surface. Multiple references to this VI generate multiple
plots for the same graph.

Note This VI appears on the block diagram when you add a Surface plot to
the front panel. You can find the Surface plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

© National Instruments 2271

 Functions

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

When x matrix, y matrix, and z matrix are the same size, the Surface plot graphs
values that correspond to each elements at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Surface Graph.vi

2272 ni.com
 Functions

Plot Helper (Matrix) VI

Graphs data with a connecting surface. Multiple references to this VI generate multiple
plots for the same graph.

Note This VI appears on the block diagram when you add a Surface plot to
the front panel. You can find the Surface plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

© National Instruments 2273

 Functions

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

When x matrix, y matrix, and z matrix are the same size, the Surface plot graphs
values that correspond to each elements at the same location in all the matrices.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Surface Graph.vi

3D Waterfall Plot Helper

Graphs the surface of the data and the area on the y-axis below the data points.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Waterfall plot to
the front panel. You can find the Waterfall plot on the 3D Graph palette.

• Plot Helper (Vector) VI

• Plot Helper (Matrix) VI

The Waterfall graph plots only the rows of x matrix, y matrix, and z matrix.

2274 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Waterfall Graph.vi

Plot Helper (Vector) VI

Graphs the surface of the data and the area on the y-axis below the data points.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Waterfall plot to
the front panel. You can find the Waterfall plot on the 3D Graph palette.

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x vector —

x vector is a 1D array that specifies the x-coordinates that graph the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

© National Instruments 2275

 Functions

standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

The Waterfall graph plots only the rows of x matrix, y matrix, and z matrix.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Waterfall Graph.vi

Plot Helper (Matrix) VI

Graphs the surface of the data and the area on the y-axis below the data points.
Multiple references to this VI generate multiple plots for the same graph.

Note This VI appears on the block diagram when you add a Waterfall plot to
the front panel. You can find the Waterfall plot on the 3D Graph palette.

2276 ni.com
 Functions

Inputs/Outputs
• 3D Plot lvclass Array in —

3D Plot lvclass Array in is a reference to the class that stores the data of the 3D plot.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates that graph the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates that graph the plot.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates that graph the plot.

• Plot ID —

Plot ID specifies the index of the plot you want to graph. When you graph more than one plot,
select the drop-down listbox under the color spectrum to the right of the graph to change the
plot.

• 3D Plot lvclass Array out —

3D Plot lvclass Array out is the graph of the 3D plot.

• error out —

error out contains error information. This output provides standard error out functionality.

The Waterfall graph plots only the rows of x matrix, y matrix, and z matrix.

© National Instruments 2277

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D\3D Waterfall Graph.vi

3D Line Plot Setup

Plots a line or curve in terms of x, y, and z points. This VI has three 1D array inputs that
specify each point on the line or curve.

Note This VI appears on the block diagram when you add a 3D Line Graph to
the front panel. You can find the 3D Line Graph on the 3D Graph palette.

Inputs/Outputs
• color vector —

color vector maps each point in the z vector to a color index on the color ramp. By default, the
values of the z vector are used as the index.

• plots in —

plots in is a reference to the class that stores the data of the 3D plot. This input allows you to
wire multiple plots.

• x vector —

x vector is a 1D array that specifies the x-coordinates of the points on the plot.

• y vector —

2278 ni.com
 Functions

y vector is a 1D array that specifies the y-coordinates of the points on the plot.

• z vector —

z vector is a 1D array that specifies the z-coordinates of the points on the plot. The x and y
vectors shift the set of data in the z vector.

• plot ID —

plot ID specifies the index of the plot you want to graph.

• plots out —

plots out is the graph of the 3D plot.

3D Surface Plot Setup

Plots a surface in terms of x, y, and z points. This VI has two 1D arrays and one 2D array
that specify each point on the plot.

Note This VI appears on the block diagram when you add a 3D Surface
Graph to the front panel. You can find the 3D Surface Graph on the 3D Graph
palette.

Inputs/Outputs
• color matrix —

color matrix maps each point in the z matrix to a color index on the color ramp. By default, the
values of the z matrix are used as the index.

• plots in —

© National Instruments 2279

 Functions

plots in is a reference to the class that stores the data of the 3D plot. This input allows you to
wire multiple plots.

• x vector —

x vector is a 1D array that specifies the x-coordinates of the points on the plot.

• y vector —

y vector is a 1D array that specifies the y-coordinates of the points on the plot.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates of the points on the plot. The x and y
vectors shift the set of data in the z matrix.

• plot ID —

plot ID specifies the index of the plot you want to graph.

• plots out —

plots out is the graph of the 3D plot.

3D Parametric Plot Setup

Plots a surface in terms of x, y, and z points. This VI has three 2D array inputs that
specify each point on the plot.

Note This VI appears on the block diagram when you add a 3D Parametric
Graph to the front panel. You can find the 3D Parametric Graph on the 3D
Graph palette

2280 ni.com
 Functions

Inputs/Outputs
• color matrix —

color matrix maps each point in the z matrix to a color index on the color ramp. By default, the
values of the z matrix are used as the index.

• plots in —

plots in is a reference to the class that stores the data of the 3D plot. This input allows you to
wire multiple plots.

• x matrix —

x matrix is a 2D array that specifies the x-coordinates of the points on the plot.

• y matrix —

y matrix is a 2D array that specifies the y-coordinates of the points on the plot.

• z matrix —

z matrix is a 2D array that specifies the z-coordinates of the points on the plot.

• plot ID —

plot ID specifies the index of the plot you want to graph.

• plots out —

plots out is the graph of the 3D plot.

XY Plot Matrix Helper

Graphs rows and columns of scatter graphs.

Note This VI appears on the block diagram when you add a XY Plot Matrix to
the front panel. You can find the XY Plot Matrix on the Graph palette.

© National Instruments 2281

 Functions

Inputs/Outputs
• 2D Plotmatrix Class Obj Array in —

2D Plot Class Obj Array in is a reference to the class that stores the data of the XY plot.

• x matrix —

x matrix specifies the x-coordinates you want to plot. The number of columns in x matrix
specifies the number of columns of individual graphs that generate when you run the VI.

• y matrix —

y matrix specifies the y-coordinates you want to plot. The number of columns in y matrix
specifies the number of rows of individual graphs that generate when you run the VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• 2D Plotmatrix Class Obj Array out —

2D Plotmatrix Class Obj Array out is the graph of the XY plot matrix.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 2D\XY Plot Matrix.vi

2282 ni.com
 Functions

3D Picture Control

Use the 3D Picture Control VIs to display graphical representations of objects in 3D

scenes.

Palette Object Description

Geometries Use the Geometries VIs to assign or configure the shapes of objects in a 3D scene.

Object Use the Object VIs to create or find objects to use in a 3D scene.

Use the Transformations VIs to apply common transformations, such as rotation,

Transformations
translation, and scaling, to objects in a 3D scene graph.

Use the File Loading VIs to load geometries of various model types in a 3D scene
File Loading
graph.

Helpers Use the Helpers VIs to perform some common tasks in setting up a 3D scene.

Geometries

Use the Geometries VIs to assign or configure the shapes of objects in a 3D scene.

© National Instruments 2283

 Functions

Palette Object Description

Sets a 3D object you create with the Create Object VI to a box by applying a box
Create Box
geometry to the object.

Applies a sphere geometry to a three-dimensional object that appears in a 3D

Create Sphere
scene.

Sets a 3D object you create with the Create Object VI to a cone by applying a cone
Create Cone
geometry to the object.

Sets a 3D object you create with the Create Object VI to a cylinder by applying a
Create Cylinder
cylinder geometry to the object.

Create Height Converts a 2D array of values to a 3D height field and applies the height field to a
Field 3D object that appears in a 3D scene.

Create Mesh Creates a 3D mesh to apply to a 3D object that appears in a 3D scene.

Create Mesh
Creates a mesh with customizable color and draw options.
with Attributes
Create 3D Axis Creates an x, y, and z axis object to define 3D space in a scene.
Sets a 3D object you create with the Create Object VI to a text object and applies
Create Text
the text, font, and color you specify to the object.
Create Text with
Creates a text object with customizable format and position options.
Alignment

Create Box
Sets a 3D object you create with the Create Object VI to a box by applying a box
geometry to the object.

2284 ni.com
 Functions

Inputs/Outputs
• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Length X —

Length X is the length of the x-axis.

• Length Y —

Length Y is the length of the y-axis.

• Length Z —

Length Z is the length of the z-axis.

© National Instruments 2285

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Box Refnum —

New Box Refnum is the reference to the created geometry.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D (ActiveX)\3D Curve Graph
(ActiveX).vi

Create Sphere
Applies a sphere geometry to a three-dimensional object that appears in a 3D scene.

Inputs/Outputs
• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

2286 ni.com
 Functions

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Radius —

Radius specifies the radius of the object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Detail —

Detail specifies the number of vertices to use in drawing the object. A higher detail value
produces a better approximation of the geometry. The default is 1.

• New Sphere Refnum —

New Sphere Refnum is the reference to the created geometry.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2287

 Functions

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi

Create Cone
Sets a 3D object you create with the Create Object VI to a cone by applying a cone
geometry to the object.

Inputs/Outputs
• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Height —

2288 ni.com
 Functions

Height specifies the length of the vertical axis of the object.

• Radius —

Radius specifies the radius of the object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Detail —

Detail specifies the number of vertices to use in drawing the object. A higher detail value
produces a better approximation of the geometry. The default is 1.

• New Cone Refnum —

New Cone Refnum is the reference to the created geometry.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Cylinder
Sets a 3D object you create with the Create Object VI to a cylinder by applying a
cylinder geometry to the object.

Inputs/Outputs
• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values

© National Instruments 2289

 Functions

0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Height —

Height specifies the length of the vertical axis of the object.

• Radius —

Radius specifies the radius of the object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Detail —

Detail specifies the number of vertices to use in drawing the object. A higher detail value
produces a better approximation of the geometry. The default is 1.

• New Cylinder Refnum —

New Cylinder Refnum is the reference to the created geometry.

2290 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Create Height Field

Converts a 2D array of values to a 3D height field and applies the height field to a 3D
object that appears in a 3D scene.

Inputs/Outputs
• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

© National Instruments 2291

 Functions

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Data —

Data is a 2D array of values that represent the height of the surface of the object at evenly spaced
intervals.

• Row Interval —

Row Interval specifies the distance between the intervals on the x-axis of the object at which the
height field Data is taken.

• Column Interval —

Column Interval specifies the distance between the intervals on the y-axis of the object at which
the height field Data is taken.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Base Height —

Base Height specifies the actual height value of the surface of the object when the value in the
height field is the minimum z value.

• New Height Field Refnum —

New Height Field Refnum is the reference to the created geometry.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Mesh
Creates a 3D mesh to apply to a 3D object that appears in a 3D scene.

2292 ni.com
 Functions

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Mesh Refnum —

New Mesh Refnum returns the reference to the mesh.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D (ActiveX)\3D Curve Graph
(ActiveX).vi

Create Mesh with Attributes

Creates a mesh with customizable color and draw options.

© National Instruments 2293

 Functions

Inputs/Outputs
• Color Array —

Color Array specifies the RGBA color values for the colors that Color Binding Mode applies to the
3D object. Color Binding Mode references only the first index in the array if you set the mode to
Overall whereas it references the respective number of indices if you set the mode to Per
Primitive or Per Vertex.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when the color is applied to the 3D
object. Alpha must be a value between 0 and 1. The default is 1.

• Color Binding Mode —

Color Binding Mode specifies the mode to use to bind color to the mesh. The mode determines
how LabVIEW assigns the color you specify in Color Array.

Note The Per Primitive and Overall modes differ in behavior only when
Draw Mode is Points, Lines, Triangles, or Quads.

0 Overall (default)—One color binds uniformly to the entire mesh.

1 Per Primitive—Different colors bind to each primitive in the mesh.
2 Per Vertex—Different colors bind to each vertex of the mesh.
3 Binding Off—No colors bind to the mesh.

• Draw Mode —

2294 ni.com
 Functions

Draw Mode specifies the mode LabVIEW uses to draw the mesh. The mode determines how
LabVIEW interprets the data you wire to Vertex Array.

0 Points (default)
1 Lines
2 Line Strip
3 Line Loop
4 Triangles
5 Triangle Strip
6 Triangle Fan
7 Quads
8 Quad Strip
9 Polygon

• Vertex Array —

Vertex Array sets the x, y, and z coordinate values in 3D space that LabVIEW uses to draw the
mesh. The settings you specify in Color Array, Draw Mode, and Indices determine how LabVIEW
interprets the vertices.

• X—

• Y—

• Z—

• Indices —

Indices determines the order in which LabVIEW processes the data in the Color Array and Vertex
Array of the mesh. For example, if Indices is [3, 2, 4, 1], then V0 appears at index 3 in the Vertex
Array, the color of V0 appears at index 3 in the Color Array, and so on.

Note If you set Color Binding Mode to Per Primitive, the color refers to the
entire face formed by V0, V1…VN (where Draw Mode determines N) rather than only
the index you specify.

• Normal Array —

Normal Array sets the x, y, and z values that define the array of normals that Normal Binding

© National Instruments 2295

 Functions

Mode applies to the 3D object.

• X—

• Y—

• Z—

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Normal Binding Mode —

Normal Binding Mode sets the binding mode for the normal vectors of the mesh. The mode
determines how LabVIEW assigns the normals you specify in Normal Array to the 3D object.
Normals determine how lights in a 3D scene affect the rendering of a 3D object.

0 Overall
1 Per Primitive
2 Per Vertex
3 Binding Off

• Texture Coordinate Array —

Texture Coordinate Array sets the s and t coordinates that define how to apply a texture to the
mesh. You must assign a texture to the mesh with the Apply Texture VI for this array to have
meaning. Each element of the array is a coordinate in a 2-D plane of domain {0..1, 0..1}, where
[0,0] is the bottom-left pixel of the image, and [1, 1] is the top-right pixel.

• S—

• T—

• New Mesh Refnum —

New Mesh Refnum returns the reference to the mesh.

• error out —

2296 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Create 3D Axis
Creates an x, y, and z axis object to define 3D space in a scene.

Inputs/Outputs
• Half plane? —

Half plane? specifies whether to use both sides of the axis boundary. The default is TRUE, which
specifies to use a half plane.

• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

© National Instruments 2297

 Functions

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Name —

Name specifies the name of the axis object.

• Length —

Length specifies the length of the axis in coordinate units. The default is 2.

• Radius —

Radius specifies the radius of the axis in coordinate units. The default is 0.01.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Axis label? —

Axis label? specifies whether to display axis labels. The default is FALSE.

• Character Size —

Character Size specifies the height of the axis label text characters in coordinate units. For
example, set character size to 1 to create an axis label equal in height to a geometric object with
a height of 1. The default is 0.5.

• New Object Refnum —

New Object Refnum returns the reference to the object.

• error out —

error out contains error information. This output provides standard error out functionality.

2298 ni.com
 Functions

Create Text
Sets a 3D object you create with the Create Object VI to a text object and applies the
text, font, and color you specify to the object.

Inputs/Outputs
• Text —

Text is the text that appears when you generate the 3D scene.

• Path to font file —

Path to font file specifies the path to the font you want to use to display the Text. LabVIEW
accepts only TrueType fonts. The path you wire to this VI must have a .ttf file extension. If you
do not wire Path to font file, LabVIEW displays the text using a Courier font.

• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

© National Instruments 2299

 Functions

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Text Refnum —

New Text Refnum returns a reference to the text, including the font and color you specify.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Text with Alignment

Creates a text object with customizable format and position options.

Inputs/Outputs
• Font Options —

Font Options specifies alignment, position, and wrap options for the text.

• Alignment —

2300 ni.com
 Functions

• Horizontal Alignment —

Horizontal Alignment specifies the horizontal alignment of the text.

0 Center
1 Left
2 Right

• Vertical Alignment —

Vertical Alignment specifies the vertical alignment of the text.

0 Base Line
1 Bottom
2 Bottom Base Line
3 Center
4 Top

• Axis Alignment —

Axis Alignment specifies the alignment of the text in relation to the x, y, and z axes.

0 Reversed X-Y
1 Reversed X-Z
2 Reversed Y-Z
3 Screen
4 X-Y
5 X-Z
6 Y-Z

• Vertical? —

Vertical? specifies whether the text runs vertically. The default is FALSE.

• Wrap Distance —

Wrap Distance specifies the distance to wrap the text in coordinate units.

© National Instruments 2301

 Functions

• Color —

Color specifies the color of the object in RGBA format. Color accepts a cluster of numeric values
0 through 1, where 0 represents the absence of the red, green, or blue color and 1 represents a
full saturation of the color. The alpha value indicates the transparency of the red, green, and
blue colors.

• Red —

Red specifies the red value. The default is 1.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity of the RGB color when you apply the color to a 3D object.
Alpha must be a value between 0 and 1. The default is 1.

• Text —

Text specifies the text of the object.

• Font Name —

Font Name specifies the font to use for the text.

If you misspell the font name or specify a font that is not installed on the computer, the
operating system selects a font.

• Character Size —

Character Size specifies the height of the text characters in coordinate units. For example, set
character size to 1 to create text characters equal in height to a geometric object with a height of
1. The default is 0.5.

• error in (no error) —

2302 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Text Refnum —

New Text Refnum returns a reference to the text, including the font and color you specify.

• error out —

error out contains error information. This output provides standard error out functionality.

Object

Use the Object VIs to create or find objects to use in a 3D scene.

Palette
Description
Object

Create
Creates a new 3D object to display in the 3D scene.
Object

Add Object Adds a 3D object to a scene.

Takes a 3D scene reference and an object name and returns the first object in the
Find Object
scene with a matching name.

Set Specifies surface properties used by lighting equations during rendering. Inputs
Material specified by this VI appear only in lit scenes.
Set
Drawing Specifies the rendering mode for 3D objects.
Style
Set
Blends fragment color outputs with destination colors for texturing 3D objects.
Blending

© National Instruments 2303

 Functions

Create Object
Creates a new 3D object to display in the 3D scene.

To display a new object in the 3D picture control, you must use the SceneObject
Properties and SceneObject Methods to set the geometric form and other attributes of
the object.

• Create Object (name) VI

• Create Object (drawable) VI
• Create Object (drawable with reference) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi
• labview\examples\Graphics and Sound\3D Picture Control\
Order of Transformations.vi
• labview\examples\Graphics and Sound\3D Picture Control\
Using Meshes.vi

Add Object
Adds a 3D object to a scene.

• Add Object (no reference) VI

• Add Object (reference) VI

2304 ni.com
 Functions

Add Object (no reference) VI

Adds a 3D object to a scene.

Inputs/Outputs
• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• New Object In —

New Object In specifies a reference to the object you want to add to the scene.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Add Object (reference) VI

Adds a 3D object to a scene.

© National Instruments 2305

 Functions

Inputs/Outputs
• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• New Object In —

New Object In specifies a reference to the object you want to add to the scene.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• New Object Out —

New Object Out returns a reference to the object you add to the scene.

• error out —

error out contains error information. This output provides standard error out functionality.

Find Object
Takes a 3D scene reference and an object name and returns the first object in the scene
with a matching name.

Inputs/Outputs
• Scene Refnum —

2306 ni.com
 Functions

Scene Refnum is the reference to the scene that contains the object.

• Object Name —

Object Name is the name of the object you want to find.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Object Refnum —

Object Refnum is the reference to the found object.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Material
Specifies surface properties used by lighting equations during rendering. Inputs
specified by this VI appear only in lit scenes.

Inputs/Outputs
• Specular —

Specular specifies the RGBA color value that represents the reflection of direct, specular light off
of the object.

© National Instruments 2307

 Functions

• Red —

Red specifies the red value. The default is 0.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity. The default value is 0.

• Ambient —

Ambient specifies the RGBA color value that indirect, ambient light affects.

• Red —

Red specifies the red value. The default is 0.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity. The default value is 0.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Color Mode —

2308 ni.com
 Functions

Color Mode specifies how the 3D object reacts to light.

0 Inherit Material (default)—The object inherits the color mode of a parent object.
Use entire Material—The emissive color of the material and its ambient, diffuse, and specular
1
reflectance values all affect the reaction of the material to a light source.
Ignore Ambient—LabVIEW ignores the ambient color and uses the base color of the object in
2
its place.
Ignore Diffuse—LabVIEW ignores the diffuse color and uses the base color of the object in its
3
place.
Ignore Specular—LabVIEW ignores the specular color and uses the base color of the object in
4
its place.
Ignore Emission—LabVIEW ignores the emissive color and uses the base color of the object in
5
its place.
Ignore Ambient and Diffuse—LabVIEW ignores the ambient and diffuse colors and uses the
6
base color of the object in their place.

• Shininess —

Shininess specifies the size of the highlight that appears on the object when light reflects
specularly off the object. Shininess can be a value from 0-128. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Emission —

Emission specifies the RGBA color value of the emissive light of the object. Emissive light
emanates from the object itself instead of an external light source.

• Red —

Red specifies the red value. The default is 0.

• Green —

Green specifies the green value. The default is 0.

• Blue —

© National Instruments 2309

 Functions

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity. The default value is 0.

• Diffuse —

Diffuse specifies the RGBA color value of the lit object. LabVIEW determines the RBGA value
based on the angle between the orientation of the object and the direction of the light source.

• Red —

Red specifies the red value. The default is 0.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity. The default value is 0.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Drawing Style

Specifies the rendering mode for 3D objects.

2310 ni.com
 Functions

Inputs/Outputs
• Face Culling Mode —

Face Culling Mode specifies whether an object's front-facing and back-facing polygons are
visible.

0 Inherit Value—Inherits the mode of the parent object.

1 No Culling—Both the front and the back side are visible.
2 Cull Back Face—Only the front side is visible.
3 Cull Front Face—Only the back side is visible.
4 Cull Both Faces—Neither the front nor the back side are visible.

• Frontface Mode —

Frontface Mode specifies the winding order of an object. Face Culling Mode interprets this input
to determine the visibility of the object's polygons.

0 Inherit Value—Inherits the mode of the parent object.

1 Counterclockwise—The object faces the front.
2 Clockwise—The object faces the back.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Mode —

Mode specifies the method you use to draw the 3D object.

0 Inherit Value (default)—Inherits the draw style of a parent object.

1 Points—Draws the object by placing points at the vertices of the object.
Wireframe—Draws the object with line segments that connect at the vertices to form a
2
bounded geometry.

© National Instruments 2311

 Functions

3 Polygon—Draws the object with a fully bounded and filled geometry.

• Size —

Size specifies the size of the points you use to draw the geometry. Set the value to -1 to inherit
the point size of a parent object. The default is -1.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Blending
Blends fragment color outputs with destination colors for texturing 3D objects.

Inputs/Outputs
• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Mode —

Mode specifies how the color values you apply to a 3D object blend.

2312 ni.com
 Functions

0 Inherit Value (default)—The object inherits the blending mode of a parent object.
1 On—Enables blending.
2 Off—Disables blending.

• Bin —

Bin specifies the draw bin in which you drop and store objects. The bin of an object affects the
order in which the object appears when you render the scene.

0 Normal Bin (default)—Stores objects without a specific sorting pattern.

Opaque Bin—Sorts objects in the scene from front to back relative to the viewer to ensure that
1
objects closer to the camera render first.
Transparent Bin—Sorts objects in the scene from back to front relative to the viewer to ensure
2
that transparent or translucent objects correctly blend with objects that appear behind them.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Destination —

Destination specifies the blend factor you apply to the color values of the currently stored pixels.

The following source and destination color components are described as (Rs, Gs, Bs, As) for
source components and (Rd, Gd, Bd, Ad) for destination components. The components have
integer values between 0 and (kR, kG, kB, kA), where kR=2mR 1, kG=2mG 1, kB=2mB 1, and
kA=2mA 1. (mR, mG, mB, mA) is the number of bitplanes for each red, green, blue, and alpha
value.

0 Zero (default)—(0, 0, 0, 0)
1 One—(1, 1, 1, 1)
2 Source Color—(RS/kR, Gs/kG, Bs/kB, As/kA)
3 One Minus Source Color—(1, 1, 1, 1)-(RS/kR, Gs/kG, Bs/kB, As/kA)
4 Source Alpha—(As/kA, As/kA, As/kA, As/kA)
5 One Minus Source Alpha—(1, 1, 1, 1)-(As/kA, As/kA, As/kA, As/kA)
6 Destination Alpha—(Ad/kA, Ad/kA, Ad/kA, Ad/kA)
7 One Minus Destination Alpha—(1, 1, 1, 1)-(Ad/kA,Ad/kA, Ad/kA, Ad/kA)

• Source —

© National Instruments 2313

 Functions

Source specifies the blend factor you apply to the color values of the incoming fragment.

The following source and destination color components are described as (Rs, Gs, Bs, As) for
source components and (Rd, Gd, Bd, Ad) for destination components. The components have
integer values between 0 and (kR, kG, kB, kA), where kR=2mR 1, kG=2mG 1, kB=2mB 1, and
kA=2mA 1. (mR, mG, mB, mA) is the number of bitplanes for each red, green, blue, and alpha
value.

0 Zero (default)—(0, 0, 0, 0)
1 One—(1, 1, 1, 1)
2 Destination Color—(Rd/kR, Gd/kG, Bd/kB, Ad/kA)
3 One Minus Destination Color—(1, 1, 1, 1)-(Rd/kR, Gd/kG, Bd/kB, Ad/kA)
4 Source Alpha—(As/kA, As/kA, As/kA, As/kA)
5 One Minus Source Alpha—(1, 1, 1, 1)-(As/kA, As/kA, As/kA, As/kA)
6 Destination Alpha—(Ad/kA, Ad/kA, Ad/kA, Ad/kA)
7 One Minus Destination Alpha—(1, 1, 1, 1)-(Ad/kA, Ad/kA, Ad/kA, Ad/kA)
8 Source Alpha Saturate—(i, i, i, 1) where i=min (As, kA, Ad)/kA

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Transformations

Use the Transformations VIs to apply common transformations, such as rotation,

translation, and scaling, to objects in a 3D scene graph.

Note LabVIEW transforms objects about their center of mass. A cone's center
of mass is one-fourth of the way from the center of the base to the vertex, not
equidistant between the highest and lowest point.

2314 ni.com
 Functions

Palette Object Description

Rotate X-axis Rotates an object about the X-axis.
Rotate Y-axis Rotates an object about the Y-axis.
Rotate Z-axis Rotates an object about the Z-axis.

Get Rotation Returns the rotation applied to an object in a 3D scene in axis-angle form.

Clears any rotations previously applied to an object in a 3D scene and rotates the
Set Rotation object by the values Axis and Angle. This VI performs an absolute rotation from
the object's initial position.

Rotates an object in a 3D scene by the values Axis and Angle. This VI performs a
Rotate Object
relative rotation from the object's current position.

Get Translation Returns the translation applied to an object in a 3D scene.

Clears any translations previously applied to an object in a 3D scene and

Set Translation translates the object by the vector you specify. This VI performs an absolute
translation from the object's initial position.

Translate Translates an object in a 3D scene by the vector you specify. This VI performs a
Object relative translation from the object's current position.

Get Scale Returns the scale factors applied to an object in a 3D scene.

Clears any previous scale operation applied to an object in a 3D scene and applies
Set Scale the scaling factors you specify. This VI performs an absolute scale from the
object's initial position.

© National Instruments 2315

 Functions

Palette Object Description

Uniformly scales an object in a 3D scene by the factors you specify. This VI

Scale Object
performs a relative scale from the object's current position.

Clear Clears any transformations previously applied to an object in a 3D scene by

Transformation modifying the identity matrices that describe the transformations.

Rotate X-axis
Rotates an object about the X-axis.

Inputs/Outputs
• Relative? —

Relative? specifies whether the rotation is relative to the axis. The default is FALSE.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• angle —

angle specifies the angle of rotation. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• angle unit —

2316 ni.com
 Functions

angle unit specifies the units of rotation in degrees or radians. The default is degrees.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Rotate Y-axis
Rotates an object about the Y-axis.

Inputs/Outputs
• Relative? —

Relative? specifies whether the rotation is relative to the axis. The default is FALSE.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• angle —

angle specifies the angle of rotation. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• angle unit —

© National Instruments 2317

 Functions

angle unit specifies the units of rotation in degrees or radians. The default is degrees.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Rotate Z-axis
Rotates an object about the Z-axis.

Inputs/Outputs
• Relative? —

Relative? specifies whether the rotation is relative to the axis. The default is FALSE.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• angle —

angle specifies the angle of rotation. The default is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• angle unit —

2318 ni.com
 Functions

angle unit specifies the units of rotation in degrees or radians. The default is degrees.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Rotation
Returns the rotation applied to an object in a 3D scene in axis-angle form.

Inputs/Outputs
• Scene Object —

Scene Object returns the Scene Object input.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object —

Scene Object is the reference to the object whose rotation you want to get.

• Axis —

Axis returns the x, y, and z coordinates that define the axis around which the rotation occurs.

• X—

© National Instruments 2319

 Functions

X indicates the x coordinate.

• Y—

Y indicates the y coordinate.

• Z—

Z indicates the z coordinate.

• Angle —

Angle returns the angle of the rotation around the axis.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Rotation
Clears any rotations previously applied to an object in a 3D scene and rotates the
object by the values Axis and Angle. This VI performs an absolute rotation from the
object's initial position.

Inputs/Outputs
• Scene Object —

Scene Object is the reference to the object you want to rotate.

• Axis —

2320 ni.com
 Functions

Axis specifies the x, y, and z coordinates that define the axis around which the rotation occurs.

• X—

X specifies the x coordinate.

• Y—

Y specifies the y coordinate.

• Z—

Z specifies the z coordinate.

• Angle —

Angle specifies the angle in radians around the Axis by which the rotation occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Rotated Scene Object —

Rotated Scene Object is the reference to the rotated 3D object.

• error out —

error out contains error information. This output provides standard error out functionality.

Rotate Object
Rotates an object in a 3D scene by the values Axis and Angle. This VI performs a
relative rotation from the object's current position.

© National Instruments 2321

 Functions

Inputs/Outputs
• Scene.Object In —

Scene.Object In is the reference to the 3D object you want to rotate.

• Axis —

Axis specifies the x, y, and z coordinates that define the axis around which the rotation occurs.

• X—

X specifies the x coordinate.

• Y—

Y specifies the y coordinate.

• Z—

Z specifies the z coordinate.

• Angle —

Angle specifies the angle in radians around the Axis by which the rotation occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene.Object Out —

Scene.Object Out returns the reference to the rotated 3D object.

• error out —

error out contains error information. This output provides standard error out functionality.

2322 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi
• labview\examples\Graphics and Sound\3D Picture Control\
Order of Transformations.vi

Get Translation
Returns the translation applied to an object in a 3D scene.

Inputs/Outputs
• Scene Object —

Scene Object is the reference to the object whose translation you want to get.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object —

Scene Object returns the Scene Object input.

• Transformation:Get Translation —

Transformation:Get Translation returns the x, y, and z factors that define the translation applied
to the Scene Object.

• X—

© National Instruments 2323

 Functions

X indicates the x factor.

• Y—

Y indicates the y factor.

• Z—

Z indicates the z factor.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Translation
Clears any translations previously applied to an object in a 3D scene and translates the
object by the vector you specify. This VI performs an absolute translation from the
object's initial position.

Use the Translate Object VI to translate an object from the object's current position.

Inputs/Outputs
• Scene Object —

Scene Object is the reference to the object you want to translate.

• Translation —

Translation contains the x, y, and z coordinates that define the vector you want to use in the
translation.

2324 ni.com
 Functions

• X—

X specifies the x coordinate.

• Y—

Y specifies the y coordinate.

• Z—

Z specifies the z coordinate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Translated Object —

Translated Object is the reference to the translated 3D object.

• error out —

error out contains error information. This output provides standard error out functionality.

Translate Object
Translates an object in a 3D scene by the vector you specify. This VI performs a relative
translation from the object's current position.

Use the Set Translation VI to translate an object from the object's initial position.

Inputs/Outputs
• Scene.Object In —

© National Instruments 2325

 Functions

Scene.Object In is the reference to the 3D object you want to translate.

• Translation —

Translation contains the x, y, and z coordinates that define the vector you want to use in the
translation.

• X—

X specifies the x coordinate.

• Y—

Y specifies the y coordinate.

• Z—

Z specifies the z coordinate.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene.Object Out —

Scene.Object Out returns the reference to the translated 3D object.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi
• labview\examples\Graphics and Sound\3D Picture Control\
Order of Transformations.vi

2326 ni.com
 Functions

Get Scale
Returns the scale factors applied to an object in a 3D scene.

Inputs/Outputs
• Scene Object —

Scene Object returns the Scene Object input.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object —

Scene Object is the reference to the object whose scale you want to get.

• Transformation:Get Scale —

Transformation:Get Scale returns the x, y, and z factors that define the scale of the Scene
Object.

• X—

X indicates the x factor.

• Y—

Y indicates the y factor.

• Z—

Z indicates the z factor.

• error out —

© National Instruments 2327

 Functions

error out contains error information. This output provides standard error out functionality.

Set Scale
Clears any previous scale operation applied to an object in a 3D scene and applies the
scaling factors you specify. This VI performs an absolute scale from the object's initial
position.

Inputs/Outputs
• Scene Object —

Scene Object is the reference to the object to which you want to apply a scale.

• Scale —

Scale specifies the x, y, and z factors that define the scale of the 3D object.

• X—

X indicates the x factor.

• Y—

Y indicates the y factor.

• Z—

Z indicates the z factor.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

2328 ni.com
 Functions

• Scaled Object —

Scaled Object is the reference to the scaled 3D object.

• error out —

error out contains error information. This output provides standard error out functionality.

Scale Object
Uniformly scales an object in a 3D scene by the factors you specify. This VI performs a
relative scale from the object's current position.

Inputs/Outputs
• Scene.Object In —

Scene.Object In is the reference to the 3D object you want to uniformly scale.

• Scale —

Scale specifies the x, y, and z factors that define the scale of the 3D object.

• X—

X indicates the x factor.

• Y—

Y indicates the y factor.

• Z—

Z indicates the z factor.

• error in (no error) —

© National Instruments 2329

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene.Object Out —

Scene.Object Out returns the reference to the scaled 3D object.

• error out —

error out contains error information. This output provides standard error out functionality.

Clear Transformation
Clears any transformations previously applied to an object in a 3D scene by modifying
the identity matrices that describe the transformations.

Inputs/Outputs
• Object Refnum In —

Object Refnum In is the reference to the object with transformations applied.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Object Refnum Out —

Object Refnum Out is the reference to the object with transformations cleared.

• error out —

error out contains error information. This output provides standard error out functionality.

2330 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi
• labview\examples\Graphics and Sound\3D Picture Control\
Order of Transformations.vi

File Loading

Use the File Loading VIs to load geometries of various model types in a 3D scene graph.

Palette
Description
Object

Loads a three-dimensional object model saved in Virtual Reality Modeling Language

Load
(VRML) format to display in a 3D scene. VRML files commonly appear with a .wrl file
VRML File
extension.

Load ASE Loads a three-dimensional object model saved in 3D Studio ASCII Exchange (ASE)
Geometry format to display in a 3D scene.

Load STL Loads a three-dimensional object model saved in ASCII stereolithography (STL) format
Geometry to display in a 3D scene.

Load VRML File

Loads a three-dimensional object model saved in Virtual Reality Modeling Language
(VRML) format to display in a 3D scene. VRML files commonly appear with a .wrl file
extension.

© National Instruments 2331

 Functions

Inputs/Outputs
• Path —

Path is the path to the WRL or VRML file.

• error in —

error out contains error information. This output provides standard error out functionality.

• Scene:Read Scene File —

Scene:Read Scene File returns the reference to the loaded file.

• error out —

error out contains error information. This output provides standard error out functionality.

Load ASE Geometry

Loads a three-dimensional object model saved in 3D Studio ASCII Exchange (ASE)
format to display in a 3D scene.

Inputs/Outputs
• Model File —

Model File is the path to the model file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

2332 ni.com
 Functions

standard error in functionality.

• New Mesh Refnum —

New Mesh Refnum returns the reference to the loaded geometry.

• error out —

error out contains error information. This output provides standard error out functionality.

Load STL Geometry

Loads a three-dimensional object model saved in ASCII stereolithography (STL) format
to display in a 3D scene.

Inputs/Outputs
• Model File —

Model File is the path to the model file.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Mesh Refnum —

New Mesh Refnum returns the reference to the loaded geometry.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2333

 Functions

Helpers

Use the Helpers VIs to perform some common tasks in setting up a 3D scene.

Palette
Description
Object

Color Converts an RGB color and an alpha into an RGBA cluster that you can apply to a 3D
Change object.

Setup
Creates a new window with hardware acceleration for rendering the 3D scene.
Window

Maps real-world data onto a 3D model.

Sensor
Mapping Use the Sensor Mapping Express VI to wire an array of data values to represent sensors
you configure using the dialog box options below.

Create
Defines a plane in the 3D scene beyond which objects cannot be drawn.
Clip Plane

New Light Creates a new light source for the 3D scene.

Creates a new texture from an image and applies the texture to the surface of an object
Texture
in the 3D scene.

Set Clip
Defines the plane beyond which LabVIEW clips, or does not render, surfaces in a scene.
Plane
Set Light Creates and positions a light source in 3D space relative to a 3D object.

Apply
Maps a texture to the surface of a 3D object. You must manually select the polymorphic
Texture

2334 ni.com
 Functions

Palette
Description
Object

instance to use.

Color Change
Converts an RGB color and an alpha into an RGBA cluster that you can apply to a 3D
object.

Inputs/Outputs
• Color —

Color is the color that you want to convert to its respective red, green, and blue components.

• Alpha —

Alpha specifies the level of opacity of the RGB color when the color is applied to the 3D object.
Alpha must be a value between 0 and 1, where 0 is transparent and 1 is opaque. The default is
1.

Note If you want the returned color to be transparent when you apply it to a
SceneObject, you must enable blending on the SceneObject and set the Blending:Bin
property to Transparent Bin.

• RGBA —

RGBA is the input color converted to the RGBA format.

• R—

R indicates the red value.

© National Instruments 2335

 Functions

• G—

G indicates the green value.

• B—

B indicates the blue value.

• A—

A indicates the Alpha value.

Setup Window
Creates a new window with hardware acceleration for rendering the 3D scene.

Inputs/Outputs
• Window State —

Window State specifies the state of the new window.

0 Open (default)—The new window is open but is not maximized, minimized, or hidden.
1 Minimized—The new window is minimized.
2 Maximized—The new window is maximized.
Hidden—The new window is floating but is not visible because LabVIEW is not the active
3
application.

• Camera Controller —

Camera Controller sets the interaction of the camera with the 3D scene.

2336 ni.com
 Functions

0 None (default)—The camera does not interact with the scene.

1 Spherical—The camera rotates and moves as if pinned to a sphere.
2 Flying—The camera flies through the scene freely.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Window Refnum —

New Window Refnum is the reference to the window.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi

Sensor Mapping
Maps real-world data onto a 3D model.

Use the Sensor Mapping Express VI to wire an array of data values to represent sensors
you configure using the dialog box options below.

© National Instruments 2337

 Functions

Dialog Box Options

Option Description
Displays a file dialog box you can use to navigate to a file of a 3D model you create using
a CAD program. LabVIEW supports the following file formats for three-dimensional
object models:

Load • Virtual Reality Modeling Language (VRML)

Model • Stereolithography (STL)

Note VRML files commonly appear with a .wrl file extension.

Model
Specifies the path to the 3D model you want to load.
Path

Displays the 3D model. Right-click the 3D model on the sensor canvas to place free
Sensor
sensors. You can configure sensors to represent NI-DAQmx channels or create free
Canvas
sensors to represent data you wire to the Express VI.

Determines how LabVIEW draws the 3D model. Use this option to ensure accurate
placement of the sensors. Select from the following options:

• Points—Draws the model by placing points at the vertices of the object.

• Wireframe+Polygons—Draws the model with line segments that connect at the
Draw
vertices to form a bounded geometry on top of the fully bounded and filled
Style
geometric 3D model.
• Wireframe—Draws the model with line segments that connect at the vertices to
form a bounded geometry.
• Polygons—Draws the model with a fully bounded and filled geometry.

Sensor Determines the size of the sensors you place on the 3D model. Use this option to ensure
Size accurate placement of the sensors.

DAQmx
Lists all NI-DAQmx tasks you create and save. Selecting a NI-DAQmx task from the pull-
Task
down menu populates the Channels List with the channels for the task.
Name

2338 ni.com
 Functions

Option Description

Note The DAQmx Task Name option does not appear unless you install NI-
DAQmx. Refer to the DAQ Getting Started Guide for more information
about installing NI-DAQmx. Refer to the NI-DAQmx Help for more
information about using NI-DAQmx channels.

Lists DAQ channels and free sensors. Select a DAQmx task from the pull-down menu.
Channels LabVIEW populates the Channels List with the channels for the DAQmx task. Drag and
List drop DAQmx task channels from the list to place sensors on the 3D model. You also can
right-click the 3D model to place free sensors on the model.

Removes a sensor from the 3D model. Select a sensor in the Channels List and click the
Delete
Delete Sensor button to remove the sensor from the list. Deleting a sensor from the 3D
Sensor
model does not delete the channel from the DAQmx task.

Configures the minimum and maximum value ranges for the incoming data. For
example, if you change the color ramp minimum to 100 and the maximum to 200, the
data values should range from 100–200. After you set the value range, click the top and
Color bottom out-of-range colors to configure the colors to indicate if a value is outside of the
Ramp value range you set.

Right-click the Color Ramp control and use the shortcut menu items to customize the
appearance, size, colors, and number of colors.

Inputs/Outputs
• Sensor Values —

Contains the sensor values. Wire a 1D array of double-precision, floating-point numbers whose
positions correspond to the order you configure the sensors in the Configure Sensors dialog
box.

• error in (no error) —

Describes error conditions that occur before this node runs.

© National Instruments 2339

 Functions

• error out —

Contains error information. This output provides standard error out functionality.

• Scene Ref Out —

Returns a reference to a 3D scene object. Wire this output to the 3D picture control to add a 3D
picture control to the front panel window and view the 3D model.

Configuring the Draw Style or Sensor Size options in the Configure Sensors dialog box
does not affect the appearance of the 3D model in the front panel window when the VI
runs. The sensors do not appear on the 3D model when the VI runs.

Components

error out passes error or warning information out of a VI to be used by other VIs. Right-
click the error out indicator on the front panel and select Explain Error or Explain
Warning from the shortcut menu for more information about the error.

source string describes the origin of the error or warning. Right-click the error out
indicator on the front panel and select Explain Error or Explain Warning from the
shortcut menu for more information about the error.

code is the error or warning code. Right-click the error out indicator on the front panel
and select Explain Error or Explain Warning from the shortcut menu for more
information about the error.

status is TRUE (X) if an error occurred or FALSE (checkmark) to indicate a warning or

that no error occurred. Right-click the error out indicator on the front panel and select
Explain Error or Explain Warning from the shortcut menu for more information about
the error.

Configures the minimum and maximum value ranges for the incoming data. For
example, if you change the color ramp minimum to 100 and the maximum to 200, the
data values should range from 100–200. After you set the value range, click the top and
bottom out-of-range colors to configure the colors to indicate if a value is outside of
the value range you set.

2340 ni.com
 Functions

Right-click the Color Ramp control and use the shortcut menu items to customize the
appearance, size, colors, and number of colors.

Specifies the path to the 3D model you want to load.

Determines how LabVIEW draws the 3D model. Use this option to ensure accurate
placement of the sensors. Select from the following options:

• Points—Draws the model by placing points at the vertices of the object.

• Wireframe+Polygons—Draws the model with line segments that connect at the
vertices to form a bounded geometry on top of the fully bounded and filled
geometric 3D model.
• Wireframe—Draws the model with line segments that connect at the vertices to
form a bounded geometry.
• Polygons—Draws the model with a fully bounded and filled geometry.

Removes a sensor from the 3D model. Select a sensor in the Channels List and click
the Delete Sensor button to remove the sensor from the list. Deleting a sensor from
the 3D model does not delete the channel from the DAQmx task.

Determines the size of the sensors you place on the 3D model. Use this option to
ensure accurate placement of the sensors.

Lists all NI-DAQmx tasks you create and save. Selecting a NI-DAQmx task from the pull-
down menu populates the Channels List with the channels for the task.

Lists DAQ channels and free sensors. Select a DAQmx task from the pull-down menu.
LabVIEW populates the Channels List with the channels for the DAQmx task. Drag and
drop DAQmx task channels from the list to place sensors on the 3D model. You also can
right-click the 3D model to place free sensors on the model.

Determines how LabVIEW draws the 3D model. Use this option to ensure accurate
placement of the sensors. Select from the following options: Points--Draws the model
by placing points at the vertices of the object. Wireframe+Polygons--Draws the model
with line segments that connect at the vertices to form a bounded geometry on top of
the fully bounded and filled geometric 3D model. Wireframe--Draws the model with
line segments that connect at the vertices to form a bounded geometry. Polygons--
Draws the model with a fully bounded and filled geometry.

© National Instruments 2341

 Functions

Determines the size of the sensors you place on the 3D model. Use this option to
ensure accurate placement of the sensors.

Lists all NI-DAQmx tasks you create and save. Selecting a NI-DAQmx task from the pull-
down menu populates the Channels List with the channels for the task.

Displays a file dialog box you can use to navigate to a file of a 3D model you create
using a CAD program. LabVIEW supports the following file formats for three-
dimensional object models:

• Virtual Reality Modeling Language (VRML)

• Stereolithography (STL)

Displays the 3D model. Right-click the 3D model on the sensor canvas to place free
sensors. You can configure sensors to represent NI-DAQmx channels or create free
sensors to represent data you wire to the Express VI.

Create Clip Plane

Defines a plane in the 3D scene beyond which objects cannot be drawn.

Inputs/Outputs
• Plane —

Plane is a cluster consisting of the four coefficients of the plane equation.

• A—

A specifies the A coefficient of the plane equation.

• B—

2342 ni.com
 Functions

B specifies the B coefficient of the plane equation.

• C—

C specifies the C coefficient of the plane equation.

• D—

D specifies the D coefficient of the plane equation.

• Number —

Number is the integer used to identify the plane. Number must be a value between 0 and 5,
inclusive.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Clip Plane Refnum —

New Clip Plane Refnum is the reference to the clip plane.

• error out —

error out contains error information. This output provides standard error out functionality.

The coordinates of points in a clip plane are determined by the following equation:

Ax+By+Cz+D = 0

LabVIEW determines the side of the plane on which objects appear based on the
orientation of the plane. A plane defined by the constants 1, 1, 1, and 0 is opposite in
orientation to a plane defined by the constants –1, –1, –1, and 0.

© National Instruments 2343

 Functions

New Light
Creates a new light source for the 3D scene.

Inputs/Outputs
• At Infinity —

At Infinity specifies whether the light source is at an infinite distance from the scene. When At
Infinity is TRUE, all light strikes the scene in parallel. The default is FALSE.

• Light Number —

Light Number is the index, or integer used to identify the light. Light Number must be a value
between 0 and 7, inclusive. You cannot index more than 8 lights in a 3D scene.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Light Refnum —

New Light Refnum is the reference to the light.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Controls and Indicators\Graphs and

Charts\Math Plots - 3D (ActiveX)\3D Curve Graph
(ActiveX).vi

2344 ni.com
 Functions

Texture
Creates a new texture from an image and applies the texture to the surface of an object
in the 3D scene.

Inputs/Outputs
• Image —

Image describes the image you want to draw or manipulate.

• image type —

image type is reserved for future use.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per
pixel.

image depth affects how LabVIEW interprets the values of image and colors.

• image —

image is an array of bytes that describes the color of each pixel in the image in raster order.
The value of image depth determines how LabVIEW interprets the value of this input.

If image depth is 24, each pixel has three bytes to describe its color. The first byte for each
pixel describes the red value, the second byte describes the green value, and the third byte
describes the blue value.

If image depth is 8, each pixel has one byte to describe its color. The value of each byte
corresponds to an element in colors, which stores 32-bit RGB values where the most-
significant byte is zero, followed in order by red, green, and blue values. Valid values include
0 through 255.

© National Instruments 2345

 Functions

If image depth is 4, the behavior is similar to when image depth is 8 except valid values in
image include 0 through 15.

If image depth is 1, any value of zero in image corresponds to element 0 in colors. All other
values correspond to element 1 in colors.

• mask —

mask is an array of bytes in which each bit describes mask information for a pixel. The first
byte describes the first eight pixels, the second byte describes the next eight pixels, and so
on.

If a bit is zero, LabVIEW draws the corresponding pixel as transparent. If the array is empty,
LabVIEW draws all pixels without transparency. If the array does not contain a bit for each
pixel in the image, LabVIEW draws any pixels missing from the array without transparency.

• colors —

colors is an array of RGB color values that correspond to the values in image. The value of
image depth determines how LabVIEW interprets the value of this input. colors stores 32-bit
RGB values where the most-significant byte is zero, followed in order by red, green, and blue
values. Valid values include 0 through 255.

If image depth is 24, LabVIEW ignores this input.

If image depth is 8, the array can have 256 elements.

If image depth is 4, the array can have 16 elements.

If image depth is 1, the array can have 2 elements.

• Rectangle —

Rectangle is a cluster that contains coordinates that describe the bounding rectangle in
which you want to draw the image.

The VI clips the image to the width and height of the rectangle. The bottom and right edges
of the rectangle bounds do not contain image pixels. Horizontal coordinates increase to the
right, and vertical coordinates increase to the bottom.

• left —

2346 ni.com
 Functions

left is the horizontal coordinate of the left edge of the rectangle.

• top —

top is the vertical coordinate of the top edge of the rectangle.

• right —

right is the horizontal coordinate of the right edge of the rectangle.

• bottom —

bottom is the vertical coordinate of the bottom edge of the rectangle.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• New Texture Refnum —

New Texture Refnum is the reference to the texture.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Graphics and Sound\3D Picture Control\3D

Model of Solar System.vi
• labview\examples\Graphics and Sound\3D Picture Control\
Using Meshes.vi

© National Instruments 2347

 Functions

Set Clip Plane

Defines the plane beyond which LabVIEW clips, or does not render, surfaces in a scene.

• Set Clip Plane (no reference) VI

• Set Clip Plane (reference) VI

Set Clip Plane (no reference) VI

Defines the plane beyond which LabVIEW clips, or does not render, surfaces in a scene.

Inputs/Outputs
• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Clip Plane Refnum In —

Clip Plane Refnum In specifies a reference to the clip plane.

• Clip Plane State —

Clip Plane State specifies whether to enable the clip plane state.

0 Inherit Value (default)—The clip plane inherits the clip plane state of a parent object.
1 Off—Disables the clip plane so it does not apply to the object.
2 On—Enables the clip plane.

• error in (no error) —

2348 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Clip Plane (reference) VI

Inputs/Outputs
• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Clip Plane Refnum In —

Clip Plane Refnum In specifies a reference to the clip plane.

• Clip Plane State —

Clip Plane State specifies whether to enable the clip plane state.

0 Inherit Value (default)—The clip plane inherits the clip plane state of a parent object.
1 Off—Disables the clip plane so it does not apply to the object.
2 On—Enables the clip plane.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

© National Instruments 2349

 Functions

standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• Clip Plane Refnum Out —

Clip Plane Refnum Out returns a reference to the clip plane object.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Light
Creates and positions a light source in 3D space relative to a 3D object.

• Set Light (no reference) VI

• Set Light (reference) VI

Set Light (no reference) VI

Creates and positions a light source in 3D space relative to a 3D object.

Inputs/Outputs
• Light State —

2350 ni.com
 Functions

Light State specifies whether to enable the light state.

0 Inherit Value (default)—The light inherits the state of the parent object.
1 Off—Disables the light.
2 On—Enables the light.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Light Refnum In —

Light Refnum In specifies a reference to the light.

• Position —

Position specifies the x, y, and z coordinates that define the position of the light relative to its
owning object.

• X—

X specifies the X coordinate of the light source. The default value is 0.

• Y—

Y specifies the Y coordinate of the light source. The default value is 0.

• Z—

Z specifies the Z coordinate of the light source. The default value is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

© National Instruments 2351

 Functions

error out contains error information. This output provides standard error out functionality.

Set Light (reference) VI

Inputs/Outputs
• Light State —

Light State specifies whether to enable the light state.

0 Inherit Value (default)—The light inherits the state of the parent object.
1 Off—Disables the light.
2 On—Enables the light.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Light Refnum In —

Light Refnum In specifies a reference to the light.

• Position —

Position specifies the x, y, and z coordinates that define the position of the light relative to its
owning object.

• X—

X specifies the X coordinate of the light source. The default value is 0.

• Y—

2352 ni.com
 Functions

Y specifies the Y coordinate of the light source. The default value is 0.

• Z—

Z specifies the Z coordinate of the light source. The default value is 0.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• Light Refnum Out —

Light Refnum In returns a reference to the light.

• error out —

error out contains error information. This output provides standard error out functionality.

Apply Texture
Maps a texture to the surface of a 3D object. You must manually select the polymorphic
instance to use.

• Apply Texture (no reference) VI

• Apply Texture (reference) VI

© National Instruments 2353

 Functions

Apply Texture (no reference) VI

Maps a texture to the surface of a 3D object. You must manually select the polymorphic
instance to use.

Inputs/Outputs
• Vertical Wrap Mode —

Vertical Wrap Mode specifies how to vertically wrap the texture around a 3D object.

Clamp (default)—The texture does not repeat across the surface of the object when you pass
0 texture coordinates outside the range [0…1]. LabVIEW interprets any texture coordinates in
Image outside this range with clamped values.
Repeat—The texture repeats across the surface of the object when you pass texture
1 coordinates outside the range [0…1]. LabVIEW only considers the fractional part of the texture
coordinate. For example, LabVIEW interprets 0.4 and 3.4 as the same texture coordinate.

• Horizontal Wrap Mode —

Horizontal Wrap Mode specifies how to horizontally wrap the texture around a 3D object.

Clamp (default)—The texture does not repeat across the surface of the object when you pass
0 texture coordinates outside the range [0…1]. LabVIEW interprets any texture coordinates in
Image outside this range with clamped values.
Repeat—The texture repeats across the surface of the object when you pass texture
1 coordinates outside the range [0…1]. LabVIEW only considers the fractional part of the texture
coordinate. For example, LabVIEW interprets 0.4 and 3.4 as the same texture coordinate.

• Scene Object In —

2354 ni.com
 Functions

Scene Object In specifies a reference to the scene you want to manipulate.

• Image Data —

Image Data specifies the image you want to apply as a texture.

• image type —

• image depth —

• image —

• mask —

• colors —

• Rectangle —

• left —

• top —

• right —

• bottom —

• Apply Mode —

Apply Mode specifies how LabVIEW applies the texture to the 3D object.

As a Decal (default)—Applies the texture as a decal, blending the colors of the texture and the
geometry of the object according to the following formula:
0
Result Color=(1–Alpha in texel)*Color of geometry+Alpha in texel*Color in texel

The alpha of the vertex does not change and is the same as the alpha in the geometry.

© National Instruments 2355

 Functions

With Modulation—Applies the texture to the surface of the object and modulates the texture by
the color of the surface according to the following formulas:
1
Result Color=Color(texel)*Color(geometry)

Result Alpha=Alpha(texel)*Alpha(geometry)

With Blending—Blends the texture with the Blend Color of the texture according to the
following formula:
2
Result Color=(–Color in texel)*Color in geometry+Color in texel*Blend Color

The resulting alpha value is Alpha(texel)*Alpha(geometry)

As a Replacement—Replaces the color of the geometry with the color of the texture. LabVIEW
3
also replaces the alpha value of the geometry with the alpha value of the texture.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Filter Mode —

Filter Mode specifies the method to use to filter the texel colors applied to the geometry.
Different values affect the quality and speed of the texture mapping.

0 No Filtration (default)—LabVIEW uses the closest texel for the texture color.
Linear Filtration—Filters the texture by taking the weighted linear average of the 2x2 array of
1
texels that lies nearest to the center of the pixels of the texture map.
Simple Mipmap Filtration—Stores mipmaps, or multiple copies of the texture, at increasingly
2 smaller resolutions. LabVIEW chooses the mipmap with texels closest in size to the pixel it is
texturing and then chooses the nearest texel as the texture color.
Bilinear Filtration—Performs a linear filtration but uses the mipmap with texels closest in size
3
to the pixel LabVIEW is texturing.
Trilinear Filtration—LabVIEW chooses the two mipmaps that are closest in size to the pixel it is
4 texturing and then performs a linear filtration on both textures. The resulting texture color is
the weighted average of the two values.

• Blend Color —

2356 ni.com
 Functions

Blend Color specifies the RGBA color to use to blend the texture you apply to the object. This
input blends a color with a texture when Apply Mode is set to With Blending.

• Red —

Red specifies the red value. The default is 0.

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity. The default value is 0.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• error out —

error out contains error information. This output provides standard error out functionality.

Apply Texture (reference) VI

Note Returns a reference to a texture in a scene.

© National Instruments 2357

 Functions

Inputs/Outputs
• Vertical Wrap Mode —

Vertical Wrap Mode specifies how to vertically wrap the texture around a 3D object.

Clamp (default)—The texture does not repeat across the surface of the object when you pass
0 texture coordinates outside the range [0…1]. LabVIEW interprets any texture coordinates in
Image outside this range with clamped values.
Repeat—The texture repeats across the surface of the object when you pass texture
1 coordinates outside the range [0…1]. LabVIEW only considers the fractional part of the texture
coordinate. For example, LabVIEW interprets 0.4 and 3.4 as the same texture coordinate.

• Horizontal Wrap Mode —

Horizontal Wrap Mode specifies how to horizontally wrap the texture around a 3D object.

Clamp (default)—The texture does not repeat across the surface of the object when you pass
0 texture coordinates outside the range [0…1]. LabVIEW interprets any texture coordinates in
Image outside this range with clamped values.
Repeat—The texture repeats across the surface of the object when you pass texture
1 coordinates outside the range [0…1]. LabVIEW only considers the fractional part of the texture
coordinate. For example, LabVIEW interprets 0.4 and 3.4 as the same texture coordinate.

• Scene Object In —

Scene Object In specifies a reference to the scene you want to manipulate.

• Image Data —

Image Data specifies the image you want to apply as a texture.

• image type —

2358 ni.com
 Functions

• image depth —

• image —

• mask —

• colors —

• Rectangle —

• left —

• top —

• right —

• bottom —

• Apply Mode —

Apply Mode specifies how LabVIEW applies the texture to the 3D object.

As a Decal (default)—Applies the texture as a decal, blending the colors of the texture and the
geometry of the object according to the following formula:
0
Result Color=(1–Alpha in texel)*Color of geometry+Alpha in texel*Color in texel

The alpha of the vertex does not change and is the same as the alpha in the geometry.

With Modulation—Applies the texture to the surface of the object and modulates the texture by
the color of the surface according to the following formulas:
1
Result Color=Color(texel)*Color(geometry)

Result Alpha=Alpha(texel)*Alpha(geometry)

2 With Blending—Blends the texture with the Blend Color of the texture according to the

© National Instruments 2359

 Functions

following formula:

Result Color=(–Color in texel)*Color in geometry+Color in texel*Blend Color

The resulting alpha value is Alpha(texel)*Alpha(geometry)

As a Replacement—Replaces the color of the geometry with the color of the texture. LabVIEW
3
also replaces the alpha value of the geometry with the alpha value of the texture.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Filter Mode —

Filter Mode specifies the method to use to filter the texel colors applied to the geometry.
Different values affect the quality and speed of the texture mapping.

0 No Filtration (default)—LabVIEW uses the closest texel for the texture color.
Linear Filtration—Filters the texture by taking the weighted linear average of the 2x2 array of
1
texels that lies nearest to the center of the pixels of the texture map.
Simple Mipmap Filtration—Stores mipmaps, or multiple copies of the texture, at increasingly
2 smaller resolutions. LabVIEW chooses the mipmap with texels closest in size to the pixel it is
texturing and then chooses the nearest texel as the texture color.
Bilinear Filtration—Performs a linear filtration but uses the mipmap with texels closest in size
3
to the pixel LabVIEW is texturing.
Trilinear Filtration—LabVIEW chooses the two mipmaps that are closest in size to the pixel it is
4 texturing and then performs a linear filtration on both textures. The resulting texture color is
the weighted average of the two values.

• Blend Color —

Blend Color specifies the RGBA color to use to blend the texture you apply to the object. This
input blends a color with a texture when Apply Mode is set to With Blending.

• Red —

Red specifies the red value. The default is 0.

2360 ni.com
 Functions

• Green —

Green specifies the green value. The default is 0.

• Blue —

Blue specifies the blue value. The default is 0.

• Alpha —

Alpha specifies the level of opacity. The default value is 0.

• Scene Object Out —

Scene Object Out returns a reference to the scene object.

• Texture Refnum —

Texture Refnum returns the reference to the texture.

• error out —

error out contains error information. This output provides standard error out functionality.

Application Control
Use the Application Control VIs and functions to programmatically control VIs and
LabVIEW applications on the local computer or across a network. You can use these VIs
and functions to configure multiple VIs at the same time.

Palette
Description
Object
Open
Application Returns a reference to a VI Server application running on the specified computer.
Reference

© National Instruments 2361

 Functions

Palette
Description
Object
Function
Open VI
Returns a reference to a VI, custom control, or global variable specified by a path to
Reference
the file on disk, name string, or existing reference.
Function
Maintains a static reference to a VI. You can configure the Static VI Reference
Static VI function to output a generic or strictly typed VI reference. After you place the Static
Reference VI Reference function on a block diagram, double-click the function to display a file
dialog box where you can select a VI.
Close
Closes a refnum associated with an open VI, VI object, an open application instance,
Reference
or a .NET, ActiveX or Python object.
Function

Returns the arguments passed from the command line when LabVIEW or a
Get LabVIEW-built application launched. User-defined arguments start after two
Command hyphens (--) surrounded by spaces in the command line.
Line
Arguments If an argument contains double quotation marks ("), this VI returns the argument
without the quotation marks.

Gets (reads) and/or sets (writes) properties of a reference. Use the property node to
Property get or set properties and methods on local or remote application instances, VIs, and
Node objects. You also can use the Property Node to access the private data of a LabVIEW
class.
Invokes a method or action on a reference. Most methods have associated
Invoke Node
parameters.
Call By Calls the VI specified by reference. The reference VI must be a strictly typed VI
Reference reference.

Starts an asynchronous call to the VI indicated by the reference input. Depending

Start
on how you prepare reference for asynchronous execution with the Open VI
Asynchronous
Reference function, you can either ignore the VI after calling it or collect its outputs
Call VI
at a later time with the Wait On Asynchronous Call node.

Wait On
Asynchronous Waits for an asynchronous call to a target VI to finish executing and then returns the
Call VI

2362 ni.com
 Functions

Palette
Description
Object

outputs of the target VI. To use the Wait On Asynchronous Call node on a reference,
you must include the 0x100 option flag as part of the options input of the Open VI
Reference function when you open the reference. You also must call the target VI
with the Start Asynchronous Call node.

To More
Typecasts a reference, such as a control or a type definition, to a more specific class
Specific Class
or interface in the inheritance hierarchy.
Function
To More
Typecasts a reference, such as a control or a type definition, to a more generic class
Generic Class
or interface in the inheritance hierarchy.
Function
Class
Selects the class of the output. You also can create a class specifier constant from a
Specifier
control refnum control or terminal.
Constant
Returns a static VI reference to the current VI by default. You can reconfigure this
reference to return a reference to the current application, to a control or indicator in
the VI, or to a pane by clicking on the block diagram icon and choosing from the
VI Server
shortcut menu. You can use this reference to access the properties and methods for
Reference
the associated VI, application, control, indicator, or pane. The VI Server Reference
always returns a fully authenticated reference. Use caution when passing
references to other VIs if you are concerned about password security.
Returns the chain of callers from the current VI to the top-level VI. Element 0 of the
Call Chain call chain array contains the name of the lowest VI in the call chain. Subsequent
Function elements are callers of the lower VIs in the call chain. The last element of the call
chain array is the name of the top-level VI.
Returns drag data from the current drag and drop operation. Only use this function
Get Drag Drop when it is necessary to access the drag data, not just to examine the data type. If a
Data Function drag and drop operation is not in progress, LabVIEW returns an error. If the data
requested is unavailable, LabVIEW returns an error.
Stops the VI in which it executes, just as if you clicked the Abort Execution button
on the toolbar. Before you call this function with a TRUE input, be sure to complete
Stop Function
all final tasks for the VI first, such as closing files, setting safe values for devices
being controlled, and so on.
Quit LabVIEW
Stops all executing VIs and ends the current instance of LabVIEW.
Function

© National Instruments 2363

 Functions

Palette
Description
Object
Sets values to the controls for the VI you reference. This function offers better
Set Control
performance than VI Server objects that write to the terminal of a front panel
Values by
control, such as using the Value property in the Control class. However, this
Index
function requires more advanced application design than other methods for setting
Function
control values.
Gets values from the controls for the VI you reference. This function offers better
Get Control
performance than VI Server objects that read from the terminal of a front panel
Values by
control, such as using the Value property in the Control class. However, this
Index
function requires more advanced application design than other methods for getting
Function
control values.

Palette You can use the Palette Editing VIs to edit the Controls or Functions palette set
Editing programmatically.

CPU Use the CPU Information functions to obtain information on the characteristics of a
Information computer or target.

Memory Use the Memory Control VIs and functions to improve LabVIEW memory
Control performance.

You can use the VI Scripting VI and functions to create, edit, and run VIs
VI Scripting
programmatically.

Application
Use the Application Builder VIs to build, deploy, or clean build specifications.
Builder

Open Application Reference Function

Returns a reference to a VI Server application running on the specified computer.

If you specify an empty string for machine name, it returns a reference to the local
LabVIEW application in which this function is running. If you do specify a machine
name, it attempts to establish a TCP connection with a remote VI Server on that

2364 ni.com
 Functions

machine on the specified port.

Inputs/Outputs
• machine name ("": open local reference) —

machine name is the address of the computer that runs an application instance to which you
want to establish a connection.

This address can be in dotted decimal notation (such as 130.164.15.250) or domain name
notation (such as foo.ni.com). An empty string causes this function to return a reference to
the local application instance.
• port number or service name (3363) —

port number or service name can accept a numeric or a string input. The default is a numeric.
port number or service name is the port on which the remote LabVIEW application is listening.

If you specify a service name, LabVIEW queries the NI Service Locator for the port number that
the server registered. The default is to use the default VI Server listener port number (3363).

To establish communication between a VI and another LabVIEW application, you must know
both the machine name and the port number or service name on which the VI Server in the
other LabVIEW application is listening. If you have more than one LabVIEW application on the
same machine, one or more of those applications may be listening on a port other than the
default VI Server listener port. In this case, make sure to supply the port number or service
name. Use the VI Server page to set the port number and service name for a VI Server or use the
Server:Port and Server:Service Name properties to set the port number or service name
programmatically.

Note The VI Server settings in the Options dialog box apply to the default application
instance, or VIs not in a project. To set VI Server settings for a project application
instance, right-click the target in the Project Explorer window.

• timeout ms (60000) —

timeout ms specifies the time, in milliseconds, that the function waits to complete and return an
error. The default value is 60,000 ms or 1 minute. A value of –1 indicates to wait indefinitely.

© National Instruments 2365

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• application reference —

application reference is the reference to the specified application.

• error out —

error out contains error information. This output provides standard error out functionality.

You can use the application reference output as an input to the Property and Invoke
Nodes to get or set properties and invoke methods on the application. Using it as the
input to the Open VI Reference function lets you get references to VIs in that
application. Close the reference with the Close Reference function. If you do not close
this reference, it closes automatically after the top-level VI associated with this
function completes execution. However, it is good practice to conserve the resources
involved in maintaining the connection by closing the reference when you finish using
it.

If you use the Open Application Reference function on a remote VI Server connection,
you may receive an error that the network connection was closed by a peer. Verify that
the machine is allowed access by selecting Tools»Options»VI Server on the server
side. You also can verify the user access settings in the User access section of the VI
Server page on the server side, also located in the Options dialog box.

Open VI Reference Function

Returns a reference to a VI, custom control, or global variable specified by a path to the
file on disk, name string, or existing reference.

2366 ni.com
 Functions

Inputs/Outputs
• type specifier VI Refnum (for type only) —

type specifier VI Refnum (for type only) determines the connector pane information and data
type of vi reference. LabVIEW ignores the actual value of this input.

By default, the function returns a Generic VI reference.

If you want to use the vi reference output of this function with the Call By Reference node or the
Start Asynchronous Call node, you must wire a strictly typed VI reference to this input.

If you wire a strictly typed VI reference to this input, the connector pane of the VI specified by vi
path must match the connector pane of this input.

• application reference (local) —

application reference is a reference to a LabVIEW application instance.

By default, LabVIEW uses the application instance of the calling VI. You can obtain references to
other application instances with the Open Application Reference function. If you wire a reference
to another application instance to the application reference input, vi path refers to a location in
the file system of the computer that is running that application instance.
• vi path —

vi path accepts a path to the VI that you want to reference, a string containing the name of the VI
that you want to reference, or a VI reference to the VI that you want to reference.

If you wire a path, LabVIEW searches for a VI in memory that you previously loaded from that
path on the same target. If you wire a name string, the string must match the full delimited name
of a VI in memory on that target. If a matching VI is not found in memory, LabVIEW then tries to
load the VI from that file on disk. An error occurs if LabVIEW cannot find the file.

If the path is relative, the VI interprets the path as relative to the caller VI or to the application
directory, if the caller VI is not saved.

Note

If you specify a remote application instance with application reference, the path is
interpreted on the remote machine in the context of the remote file system. The path
is expressed using the local computer's path separators, but is translated to the
remote computer's path separators when the request arrives there.

© National Instruments 2367

 Functions

For example, to reference a VI on Linux at My HD/LabVIEW Vis/foo.vi from a

Windows–based application, use the path My HD:\LabVIEW Vis\foo.vi.
Conversely, to reference a VI on a computer running Windows at C:\labview\
foo.vi from an Linux application, wire the path C/labview/foo.vi.

If you wire a path or you wire both VI and application references, LabVIEW waits until the user
interface is idle to load the VI from disk. If you wire a name string or a VI reference without an
application reference, LabVIEW does not need to wait until the user interface is idle, as it does
not load a VI from disk. LabVIEW will only search in memory for a VI with a specified name.

Note LabVIEW does not support the ability to open a reference to a clone VI using a
name with the Open VI Reference function. Using this function to open a reference to
a clone VI may cause LabVIEW to crash.

• options —

options determines characteristics of the VI referenced by vi reference, including whether you

can call the VI asynchronously. The default is 0x0.

Create options by combining a subset of the following option flags.

Option
Description
flag
Record modifications—Use this option flag when you want an asterisk (*) to appear by
0x01 the VI title when changes have been made using VI Server. The VI must be in edit mode
for LabVIEW to record the modifications.
Open templates for editing—Use this option flag to open the original .vit file. If you do
not select this option flag, LabVIEW opens a new instance of the template VI. Edits made
0x02
to an instance do not affect the original .vit file. This option flag has no effect on non-
template files.
Prompt user to save—Use this option flag to prompt the user to save changes when this
VI reference closes if all the following conditions are true:
• The referenced VI or its subVIs contain unsaved changes.
0x04 • There are no other open references to the referenced VI.
• The referenced VI is able to leave memory. A VI is able to leave memory, for example,
if no other VIs call the VI, the front panel of the VI is closed, and the VI is not a
member of an open project library, and so on.

2368 ni.com
 Functions

Option
Description
flag

Prepare for reentrant run—Use this option flag when you want a reference to a reentrant
clone of the target VI, instead of the target VI itself. Reentrant clones of a VI allow you to
open multiple front panels of the same VI or to run multiple copies of the same VI in
parallel. For each reference to the target VI, LabVIEW creates a separate clone of the
target VI. This clone is not part of the pool of shared clones used by regular subVI calls.

LabVIEW ignores this flag if you wire the type specifier VI Refnum (for type only) input
because when you provide a type specifier, you can always get a reentrant clone if the
0x08 target VI is reentrant. LabVIEW returns error 1096 if the target VI is not reentrant.

Tip Use this flag in combination with the Run VI method to execute multiple
reentrant clones in parallel. Use the Start Asynchronous Call node instead of
the Run VI method to run target VIs asynchronously. In addition to providing a
simpler interface and better performance, the Start Asynchronous Call node
allows you to collect the outputs of the target VI with a corresponding Wait On
Asynchronous Call node.

Prompt to find missing subVIs—Use this option flag to prompt the user to allow LabVIEW
0x10
to search for missing subVIs of the referenced VI.
Hide loading dialog box—Prevents LabVIEW from displaying the loading dialog box
when searching for missing subVIs of the referenced VI.

0x20
Note This option flag does not affect whether LabVIEW prompts you to find
the missing VIs or not.

Enable simultaneous calls on reentrant VIs—Use this option flag when you want to use
multiple Call By Reference or Start Asynchronous Call nodes to execute clones of a
reentrant target VI in parallel, as when you use these nodes within a For Loop with
parallel loop iterations. This option flag enables parallel execution because it gives each
Call By Reference node access to the data spaces of the clone VIs. If you do not use this
option flag, calls to the same target VI execute one at a time because they must wait for
0x40 access to the same data space.

The 0x40 option flag is valid only in the following situations:

• The target VI is reentrant and shares clones.

• The target VI is reentrant, and you also include either the 0x80 or the 0x100 option
flag.

© National Instruments 2369

 Functions

Option
Description
flag

Note LabVIEW returns error 1591 if the 0x40 option flag is not valid for the
target VI or the other included option flags.

Prepare to call and forget—Use this option flag when you want to call a target VI
asynchronously with the Start Asynchronous Call node but you do not need to know
when or what the VI returns. Do not use this option flag with 0x08 or 0x100.
0x80
Note LabVIEW returns error 1578 if you use this option flag with a reference
to a remote VI.

Prepare to call and collect—Use this option flag when you want to collect the results of
an asynchronous call to a target VI with the Wait On Asynchronous Call node. If you use
this option flag, you must include one Wait On Asynchronous Call node for every call that
you begin with a Start Asynchronous Call node to ensure that LabVIEW does not retain
0x100 any started calls in memory indefinitely. Do not use this option flag with 0x08 or 0x80.

Note LabVIEW returns error 1578 if you use this option with a reference to a
remote VI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• password ("") —

password is the password for the VI whose reference you want to open.

Wire a password to this input if you want to edit a password-protected target VI. If you wire the
correct password, the function returns an authenticated reference to the VI. If you wire an
incorrect password to this input, the function returns an error and an invalid VI reference.
LabVIEW ignores this input if the target VI is not password-protected. If you do not wire a
password to this input and the target VI is password-protected, the Open VI Reference function
returns a valid reference, but you cannot use the reference to edit the VI.

Note You can also use a VI Server Reference to get an authenticated reference to a VI.

• vi reference —

2370 ni.com
 Functions

vi reference is the refnum associated with the requested VI.

If the function fails, vi reference contains Not A Refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

The Open VI Reference function prepares a VI reference for dynamic calls by the Call By
Reference node, the Start Asynchronous Call node, and the Wait On Asynchronous Call
node. Use the type specifier VI Refnum (for type only) and the options inputs to
prepare a reference for dynamic execution.

Opening References for Dynamic VI Calls

If you want to call the specified VI dynamically with the Call By Reference Node or the
Start Asynchronous Call Node, you must use appropriate data for the following
parameters:

• type specifier VI Refnum (for type only)—Wire a strictly typed VI reference to this
input.
• options—Determine whether the 0x08, 0x40, 0x80, and 0x100 option flags apply to
the way you want to call the referenced VI.

Criteria for Opening Strictly Typed References

If you wire a strictly typed VI reference to the type specifier VI Refnum (for type only),
the VI specified by vi path must meet the following criteria:

• The VI cannot be broken.

• The VI cannot be active as a top-level VI unless the VI is reentrant.
• The connector pane of the VI must match the connector pane of type specifier VI
Refnum (for type only).

Opening References to Reentrant VIs

If you open a reference to a reentrant VI, consider the following details:

• Dynamic calls to reentrant target VIs execute serially unless you specify 0x40 as

© National Instruments 2371

 Functions

one of the options.

• If you use the 0x40 option flag to execute instances of a reentrant target VI in
parallel, vi reference refers to the target VI rather than to a clone of the target VI.
However, both the Call By Reference node and the Start Asynchronous Call node
call a clone of the target VI. Therefore, if you call a VI Server property or method on
vi reference, the property or method does not affect the clone VIs that those nodes
actually call.
• The Equal? function always returns TRUE when you compare two references to the
same reentrant VI. To determine whether the references refer to the same instance
of the reentrant VI, use the Type Cast function to convert the references to 32-bit
signed integers. Then use the Equal? Function to compare those integers.

Aborting Open References

You can abort all open VI references either manually from the front panel of the VI or
by using the Abort VI method. However, VI references prepared for asynchronous
execution have important caveats depending on the options used to open the
reference:

• 0x80—A call-and-forget VI aborts only if you manually abort it from its front panel
or call the Abort VI method on it. Otherwise, the VI runs to completion, even if you
close the reference or abort the calling VI.
• 0x100—Call-and-collect VIs abort for the following reasons:
◦ You abort the VI that opened the call-and-collect VI reference. In this case,
LabVIEW aborts all running instances of the VI.
◦ You manually abort a specific instance of the VI. In this case, exactly one Wait
On Asynchronous Call node returns an error indicating that the called VI
aborted. All other Wait On Asynchronous Call nodes that are waiting on calls to
the same VI reference continue waiting.
◦ You call the Abort VI method on the call-and-collect VI reference. In this case,
LabVIEW aborts all currently running instances of the VI. A corresponding
number of Wait On Asynchronous Call nodes return errors.

Closing Open References

After you finish using a reference that you obtain with this function, close the reference
with the Close Reference function. Explicitly closing a reference enables LabVIEW to
free the resources involved in maintaining that reference, thereby contributing to

2372 ni.com
 Functions

optimal memory allocation and performance. Otherwise, LabVIEW cannot close the
reference until the VI that opened the reference finishes executing.

Note Closing a reference that was opened with the 0x80 option flag does not
abort the referenced VI.

Opening a VI Reference in a Stand-Alone Application

If you want to dynamically open a VI on both the development computer and within a
stand-alone application, use a relative path for vi path.

Miscellaneous Details

• If you set the Execution:Run When Opened, Execution:Show Front Panel On Load,
or Execution:Show Front Panel On Call properties or the corresponding options in
the VI Properties dialog box of the target VI, LabVIEW ignores the settings.
• To open a new Facade VI reference, wire a FacadeVI class to type specifier VI
Refnum (for type only).

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Server\

Asynchronous Call By Reference\Asynchronous Call and
Collect (Using Option 0x40).vi
• labview\examples\Application Control\VI Server\
Asynchronous Call By Reference\Asynchronous Call and
Forget.vi
• labview\examples\Application Control\VI Server\
Asynchronous Call By Reference\Asynchronous Call and
Collect.vi

Static VI Reference

Maintains a static reference to a VI. You can configure the Static VI Reference function
to output a generic or strictly typed VI reference. After you place the Static VI Reference

© National Instruments 2373

 Functions

function on a block diagram, double-click the function to display a file dialog box
where you can select a VI.

Inputs/Outputs
• —

vi reference is the refnum associated with the configured VI.

If the VI is not valid, vi reference contains Not A Refnum.

The Static VI Reference function acts as a subVI and appears in the VI hierarchy of the
top-level VI. By default, the output is a generic VI reference.

You can change the output of this function to a strictly typed VI reference. Right-click
the function and select Strictly Typed VI Reference from the shortcut menu to change
the output. A red star in the upper left corner of the function icon indicates the
reference is strictly typed. The strictly typed VI reference identifies the connector pane
of the VI you are calling. You can create a strictly typed VI reference only from a VI or VI
template, not from a polymorphic VI or other non-VI file such as a global variable or
control.

Use a strictly typed VI reference if you want to call the referenced VI with the Call By
Reference node or the Start Asynchronous Call node. When you create a strictly typed
VI reference, you cannot wire vi reference to the Run VI method. You cannot use the
Run VI method to run a VI that is already reserved for execution by another VI. A strictly
typed static VI reference also reserves any subVIs when a top-level VI is reserved, thus
making it ineligible for the Run VI method. Refer to the Run VI method for more
information.

LabVIEW loads the referenced VI into memory when you load the top-level VI. When
the Static VI Reference function outputs a strictly typed VI reference, LabVIEW reserves
the referenced VI as long as the top-level VI is running. LabVIEW closes this reference
when the top-level VI is no longer in memory. You do not have to explicitly close the
reference this function returns.

2374 ni.com
 Functions

Note LabVIEW does not check whether the referenced VI can compile. If the
referenced VI is broken, LabVIEW does not recognize that it is broken until
you run the top-level VI. If you execute an Open VI Reference function that
references the broken VI, you receive an error.

If you want LabVIEW to check for a broken referenced VI before you run the
top-level VI, use the referenced VI directly in the top-level VI instead of using a
Static VI Reference function by clicking the Select a VI icon or text on the
Functions palette and navigating to the VI you want to add to the block
diagram.

Close Reference Function

Closes a refnum associated with an open VI, VI object, an open application instance, or
a .NET, ActiveX or Python object.

Inputs/Outputs
• reference —

reference is the refnum associated with an open VI, VI object, an open application instance, or a
.NET or ActiveX object. reference also accepts 1D arrays of references.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2375

 Functions

When you create a refnum to a VI, LabVIEW loads the VI into memory. The VI stays in
memory until you close the refnum and until the VI meets the following conditions:

• There are no other open references to the referenced VI.

• The front panel of the VI is not open.
• The VI is not a subVI of another VI in memory.
• The VI is not a member of an open project library.

Get Command Line Arguments

Returns the arguments passed from the command line when LabVIEW or a LabVIEW-
built application launched. User-defined arguments start after two hyphens (--)
surrounded by spaces in the command line.

If an argument contains double quotation marks ("), this VI returns the argument
without the quotation marks.

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• application name —

application name returns the name of the application that launched this VI. The application can
be LabVIEW or a LabVIEW-built application.

• arguments —

arguments returns the user-defined arguments passed from the command line. User-defined
arguments start after two hyphens (--) surrounded by spaces in the command line.

• error out —

2376 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

For example, if you enter C:\temp\MyLabVIEWApp.exe -- abc 123 TRUE in

the command line when launching a LabVIEW-built application, application name
returns MyLabVIEWApp.exe and arguments returns an array of the following strings:
"abc", "123", "TRUE".

Property Node

Gets (reads) and/or sets (writes) properties of a reference. Use the property node to get
or set properties and methods on local or remote application instances, VIs, and
objects. You also can use the Property Node to access the private data of a LabVIEW
class.

The Property Node automatically adapts to the class of the object that you reference.
LabVIEW includes Property Nodes preconfigured to access XML Properties, VISA
properties, .NET properties, and ActiveX properties.

Inputs/Outputs
• reference —

reference is the refnum associated with the object for which you want to set or get properties.

If the Property Node class is Application or VI, you do not have to wire a refnum to this input. For
the Application class, the default is the current application instance. For the VI class, the default
is the VI containing the Property Node.

You also can wire a LabVIEW class to the reference input to access the private data of the
LabVIEW class.

• error in (no error) —

© National Instruments 2377

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Property —

property 2..n are examples of properties you want to set (write).

• reference out —

reference out returns reference unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

• Property —

property 1..n are examples of properties you want to get (read).

To select the class on which to execute the property, wire the refnum to the reference
input. For example, to select the VI, Generic, or Application class, wire the VI, VI object,
or application reference to the reference input. The node adapts to the class
automatically. You also can right-click the node and select a class from the shortcut
menu.

You can wire a LabVIEW class to the reference input of a Property Node. If the LabVIEW
class has accessor VIs that you can access through a Property Node, you can read from
or write to the accessor VIs using a Property Node.

You can quickly view the implementation of a LabVIEW class property if the block
diagram of the accessor VI is available. To view the implementation of a LabVIEW class
property, right-click the property and select Open Accessor VI from the shortcut menu.
If the property is dynamic with more than one implementation, selecting this option
displays the Choose Implementation dialog box. Use this dialog box to view all
implementations of the property, or dynamic dispatch member VI, and open one or
more implementations.

Note If you do not wire the Property Node, the class property still executes

2378 ni.com
 Functions

at run-time.

If the Property Node opens and returns a reference to an object, use the Close
Reference function to close the reference.

Move the cursor over terminals in the Property Node to display more information
about the property in the Context Help window. You also can right-click a property
terminal and select Help For Property from the shortcut menu, where Property is
the name of the property.

You can read or write multiple properties using a single node. However, some
properties are not readable and some are not writable. Use the Positioning tool to
resize the Property Node to add new terminals. A small direction arrow to the right of
the property indicates a property you read. A small direction arrow to the left of the
property indicates a property you write. Right-click the property and select Change to
Read or Change to Write from the shortcut menu to change the operation of the
property.

The node executes from top to bottom. The Property Node does not execute if an error
occurs before it executes, so always check for the possibility of errors. If an error
occurs in a property, LabVIEW ignores the remaining properties and returns an error. If
you right-click the Property Node and select Ignore Errors Inside Node, LabVIEW
executes the remaining properties on the Property Node. Only the first error is
returned by the Property Node. The error out cluster contains information about
which property caused the error.

Properties have a short or long name that you can change by right-clicking and
selecting Name Format from the shortcut menu. The No Names format displays only
the data type for each property.

Note You can right-click the Property Node and select Downcast to Class
from the shortcut menu to typecast a reference to a more specific class in the
inheritance hierarchy. For example, select Downcast to Class from an
Interchangeable Virtual Instruments (IVI) class driver to view the IVI specific
driver properties. This item is not supported for all class types. If Downcast
to Class is disabled, you can use the To More Specific Class and To More

© National Instruments 2379

 Functions

Generic Class functions.

Invoke Node

Invokes a method or action on a reference. Most methods have associated parameters.

If the node is configured for VI Server Application class or Virtual Instrument class and
reference is unwired, reference defaults to the current Application or VI. LabVIEW
includes Invoke Nodes preconfigured to access XML methods, .NET methods, and
ActiveX methods.

Inputs/Outputs
• reference —

reference is the refnum associated with the object on which you want to invoke a method or
perform an action. If the Invoke Node class is Application or VI, you do not have to wire a refnum
to this input. For the Application class, the default is the current application instance. For the VI
class, the default is the VI containing the Invoke Node.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• input 1 —

input 1..n are example input parameters of a method.

• reference out —

reference out returns reference unchanged.

• error out —

2380 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

• return value —

return value is an example return value of a method.

• output 1 —

output 1..n are example output parameters of a method.

To select the class on which to execute the method, wire the refnum to the reference
input. For example, to select the VI, Control, or Application class, wire the VI, VI object,
or application reference to reference. The node adapts to the class automatically. You
also can right-click the node and select a class from the shortcut menu.

Right-click the node and select Help For Method from the shortcut menu, where
Method is the name of the method, for more information about the method and its
parameters.

You can get (read) and set (write) the values of the method parameters. Parameters
with a white background are required inputs and the parameters with a gray
background are recommended inputs.

If the small direction arrow on the parameter is on the right, you are getting the
parameter value. If the small direction arrow on a parameter is on the left, you are
setting the parameter value. Methods have a short or long name that you can change
by right-clicking and selecting Name Format from the shortcut menu. The No Names
format displays only the data type for each method.

Note You can right-click the Invoke Node and select Downcast to Class from
the shortcut menu to typecast a reference to a more specific class in the
inheritance hierarchy. For example, select Downcast to Class from an
Interchangeable Virtual Instruments (IVI) class driver to view the IVI specific
driver properties. This item is not supported for all class types. If Downcast
to Class is disabled, you can use the To More Specific Class and To More
Generic Class functions.

© National Instruments 2381

 Functions

.NET Invoke Node (Windows)

If you right-click the Invoke Node and select Select Class».NET»Browse from the
shortcut menu, LabVIEW displays the Select Object From Assembly dialog box.

On the front panel or block diagram, right-click a .NET object, select Create»Invoke
Node, and select a method from the shortcut menu to invoke a method for the object.
You also can invoke .NET-specific methods for a .NET object. On the block diagram,
right-click a .NET object, select Create»Invoke Node, and select a .NET-specific
method from the shortcut menu.

ActiveX Invoke Node (Windows)

ActiveX does not support 64-bit integer data types. If you wire 64-bit integer data to a
variant parameter of an ActiveX Invoke Node, LabVIEW converts the data to a double-
precision, floating-point number. If you right-click the Invoke Node and select Select
Class»ActiveX»Browse from the shortcut menu, LabVIEW displays the Select Object
From Type Library dialog box.

On the front panel or block diagram, right-click an ActiveX object, select

Create»Invoke Node, and select a method from the shortcut menu to invoke a method
for the object. You also can invoke ActiveX-specific methods for an ActiveX object. On
the block diagram, right-click an ActiveX object, select Create»Invoke Node, and select
an ActiveX-specific method from the shortcut menu.

Call By Reference

Calls the VI specified by reference. The reference VI must be a strictly typed VI

reference.

Inputs/Outputs
• reference —

2382 ni.com
 Functions

reference is the refnum associated with a VI that is already open.

The reference must be a strictly typed VI reference.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• reference out —

reference out returns reference unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Both the Call By Reference node and the subVI node call a VI. The Call By Reference
node enables you to call any VI dynamically whose connector pane matches that of the
strictly typed reference input. Use the Open VI Reference function to obtain a strictly
typed reference. A subVI node only allows you to call a specific VI that is statically
determined when you place the subVI node on the block diagram.

Interface Details

The interface of this node includes the following features:

• Accessing inputs and outputs of the target VI—When you wire a strictly typed VI
reference to the reference input of the Call By Reference node, the node displays
the connector pane of the referenced VI. Wire data to the input terminals of the
connector pane to pass the data to the called VI. Use the output terminals of the
connector pane to access the data that the called VI returns.
• Changing the connector pane of a wired Call By Reference node—To force the Call
By Reference node to display a different connector pane after you change the
reference input, right-click the node and select Adapt To Reference Input from the
shortcut menu.

© National Instruments 2383

 Functions

Execution Details

This node exhibits the following execution behaviors:

• Synchronous execution—Like most block diagram objects, the Call By Reference

node executes synchronously, preventing data flow from continuing along its
output wires until the target VI finishes executing. If you want to run the target VI
asynchronously while the block diagram beyond the VI call continues executing,
use the Start Asynchronous Call node instead.
• Performance overhead for calling a VI dynamically—The overhead for calling a VI
by reference in the local application instance is negligible compared to the
overhead of using a subVI node. LabVIEW requires significantly more overhead to
call a VI by reference in a remote application instance.

Alternative Ways to Call a VI

The Call By Reference node is not the best choice for dynamically calling a VI in the
following circumstances:

• Asynchronous execution—If you want to call a target VI asynchronously, use the

Start Asynchronous Call node instead of the Call By Reference node.
• Opening the front panel of a target VI without running the VI—If you want to
open the front panel of a target VI without causing the VI to run, use the Front
Panel:Open method instead of the Call By Reference node.

Start Asynchronous Call VI

Starts an asynchronous call to the VI indicated by the reference input. Depending on

how you prepare reference for asynchronous execution with the Open VI Reference
function, you can either ignore the VI after calling it or collect its outputs at a later time
with the Wait On Asynchronous Call node.

2384 ni.com
 Functions

Inputs/Outputs
• reference —
reference is a reference to a target VI that you want to call asynchronously.
The reference must meet the following criteria:
• Be strictly typed
• Be prepared for asynchronous execution by the Open VI Reference function using either the
0x80 or 0x100 option flag. You can combine other option flags with these asynchronous
options.
• error in (no error) —
error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.
• reference out —
reference out returns reference unchanged.
• error out —
error out contains error information. This output provides standard error out functionality.

Interface Details

The interface of this node includes the following features:

• Access to inputs of the target VI—When you wire a strictly typed VI reference to the
reference input of the Start Asynchronous Call node, the node displays the input
portion of the connector pane of the referenced VI. Wire data to the input terminals
of the connector pane to pass the data to the target VI.
• No access to outputs of the target VI—Because the purpose of the Start
Asynchronous Call node is to start a VI call without waiting for it to complete, the
outputs of the VI call are not available from the Start Asynchronous Call node. To
collect the outputs of the target VI, use the Wait On Asynchronous Call node.

Execution Details

This node exhibits the following execution behaviors:

• Serial or parallel execution—When you pass the same VI reference to multiple

Start Asynchronous Call nodes, LabVIEW serializes the calls by default. To allow
parallel execution, make the target VI reentrant and set the 0x40 option flag when
you open its reference with the Open VI Reference function. Regardless of whether
the calls execute serially or simultaneously, this node returns immediately,
allowing dataflow to continue in the calling VI.

© National Instruments 2385

 Functions

• If you include 0x40 as part of the options input, VI Server properties and
methods do not modify called VI clones—If you set the 0x40 option flag when you
open a reference to a target VI, the Start Asynchronous Call node starts a call to a
clone of the referenced VI, not to the referenced VI itself. Therefore, if you call a VI
Server property or method on the original reference that the Open VI Reference
function returns, the effects of that property or method are not reflected in the VI
clone that the Start Asynchronous Call node actually calls. To perform VI Server
tasks such as opening or positioning the front panel on the VI that is actually
called, you must call the property or method within the reentrant VI itself.
• Does not require the user interface thread to be idle

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Server\

Asynchronous Call By Reference\Asynchronous Call and
Forget.vi
• labview\examples\Application Control\VI Server\
Asynchronous Call By Reference\Asynchronous Call and
Collect.vi

Wait On Asynchronous Call VI

Waits for an asynchronous call to a target VI to finish executing and then returns the
outputs of the target VI. To use the Wait On Asynchronous Call node on a reference,
you must include the 0x100 option flag as part of the options input of the Open VI
Reference function when you open the reference. You also must call the target VI with
the Start Asynchronous Call node.

Inputs/Outputs
• reference —

2386 ni.com
 Functions

reference is a reference to a target VI that you want to call asynchronously.

The reference must meet the following criteria:
• Strictly typed
• Prepared for asynchronous execution by the Open VI Reference function with the 0x100
option flag. You can combine other option flags with this option.
• Called by a Start Asynchronous Call node elsewhere in the calling VI
• error in (no error) —
error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.
• reference out —
reference out returns reference unchanged.
• error out —
error out contains error information. This output provides standard error out functionality.

Interface Details
The interface of this node includes the following features:

• No access to inputs of the target VI—The Wait On Asynchronous Call node does
not provide access to the inputs of the target VI. You can pass inputs to the target VI
when you call it with a Start Asynchronous Call node.
• Access to outputs of the target VI—When you wire a strictly typed VI reference to
the reference input of the Wait On Asynchronous Call node, the node displays the
output portion of the connector pane of the referenced VI. Use the output
terminals of the connector pane to access the data returned by the target VI.

Execution Details
This node exhibits the following execution behaviors:

• Ability to wait for only a specified amount of time—To specify how long this node
waits for the associated asynchronous call to complete, right-click the node and
select Timeout from the shortcut menu to display the Timeout for Wait On
Asynchronous Call dialog box. Use this dialog box to specify how long the node
waits on the corresponding VI call before returning a timeout error.
• Ability to wait on multiple calls to the same VI reference—If you pass the same VI
reference to multiple Start Asynchronous Call nodes, you cannot predict which
Wait On Asynchronous Call node will detect the completion of each call. You can
take precautions to match a Wait On Asynchronous Call Node to a specific VI call if
necessary.

© National Instruments 2387

 Functions

• Does not require the user interface thread to execute

Caveats and Recommendations

• Can be called before the corresponding Start Asynchronous Call node

• Every Start Asynchronous Call node that uses a 0x100 reference must have a
corresponding Wait On Asynchronous node—If you start an asynchronous call to a
call-and-collect reference, LabVIEW cannot free the reference until a Wait On
Asynchronous Call node collects the outputs of the VI call to that reference.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Server\

Asynchronous Call By Reference\Asynchronous Call and
Collect.vi
• labview\examples\Application Control\VI Server\
Asynchronous Call By Reference\Asynchronous Call and
Collect (Using Option 0x40).vi

To More Specific Class Function

Typecasts a reference, such as a control or a type definition, to a more specific class or

interface in the inheritance hierarchy.

For example, if Class A inherits from Class B, a variable of type B can hold a value of
type A. You can use the function to downcast from type B to type A. If the typecast is
invalid, this function returns an error at run time.

You can use the To More Specific Class function for casting any class hierarchy in
LabVIEW, including VI Server refnums, .NET/ActiveX refnums, and LabVIEW classes or
interfaces.

2388 ni.com
 Functions

Inputs/Outputs
• target class —

target class is the class or interface to which you want to downcast reference.

You can wire a class specifier constant or any wire of the target type to this input.
• reference —

reference is the refnum or LabVIEW class or interface to downcast.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• specific class reference —

specific class reference is the downcast reference.

If the target class is incompatible with the reference, the function returns an error and specific
class reference is Not A Refnum.
• error out —

error out contains error information. This output provides standard error out functionality.

You can use the To More Specific Class function to manipulate the properties or
methods from a more specific class or interface than that of the reference. For
example, if you build an array of references to boolean, numeric, and string controls,
LabVIEW casts these references to the more generic Control class because an array can
contain only one data type, and each of these controls is a member of the Control
class. If you then want to manipulate the properties for only the boolean controls in
the array, you can create a reference to the array and use the To More Specific Class
function to downcast the array reference to the Boolean class.

Wire a VI refnum to reference and a Facade VI refnum to target class to downcast from
VI to Facade VI.

You also can use data value references to downcast classes. The To More Specific Class
function waits to execute until the reference is available for downcast. To downcast a
class or interface, wire the data value reference of the target class or interface to target

© National Instruments 2389

 Functions

class.

Related Information

Casting LabVIEW Classes

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Server\To More

Specific Class\To More Specific Class.vi

To More Generic Class Function

Typecasts a reference, such as a control or a type definition, to a more generic class or

interface in the inheritance hierarchy.

For example, if Class A inherits from Class B, the function upcasts a variable of type A
to a variable of type B.

You can use the To More Generic Class function for casting any class hierarchy in
LabVIEW, including VI Server refnums, .NET/ActiveX refnums, and LabVIEW classes or
interfaces.

Inputs/Outputs
• target class —

target class is the class or interface to which you want to upcast reference.

You can wire a class specifier constant or any wire of the target type to this input.
• reference —

reference is the refnum or LabVIEW class or interface to upcast.

2390 ni.com
 Functions

• generic class reference —

generic class reference is the upcasted reference.

If an error occurs, generic class reference is Not A Refnum.

This function does not have error in and error out parameters because LabVIEW can
determine at edit time whether you have wired the reference to a compatible target
class. If you wire the reference to an incompatible target class, the wire breaks and
you receive a Class conflict error.

You can use the To More Generic Class function to manipulate the properties or
methods from a more generic class or interface than that of the reference. For
example, you can wire an enum control reference to the To More Generic Class
function to upcast the reference to the Numeric class. You then can manipulate the
Numeric class properties of the control, but you no longer can access the specific
properties of the Enum class.

Wire a Facade VI refnum to reference and a VI refnum to target class to upcast from
Facade VI to VI.

Related Information

Casting LabVIEW Classes

Class Specifier Constant

Selects the class of the output. You also can create a class specifier constant from a
control refnum control or terminal.

You can use the Class Browser window to create a class specifier constant for some VI
Server classes.

Use this constant with the To More Specific Class or To More Generic Class functions.
Since the value of the constant is always Not A Refnum, you cannot wire this
constant to the input of a Property Node.

© National Instruments 2391

 Functions

VI Server Reference

Returns a static VI reference to the current VI by default. You can reconfigure this
reference to return a reference to the current application, to a control or indicator in
the VI, or to a pane by clicking on the block diagram icon and choosing from the
shortcut menu. You can use this reference to access the properties and methods for
the associated VI, application, control, indicator, or pane. The VI Server Reference
always returns a fully authenticated reference. Use caution when passing references to
other VIs if you are concerned about password security.

You also can right-click a front panel object or terminal and select Create»Reference
from the shortcut menu to create a VI Server reference.

To link the reference constant to the current application, VI, or a pane of the current VI,
click the VI Server reference on the block diagram and select This Application, This VI,
or Pane. You also can right-click the VI Server reference and select Link to»This
Application, Link to»This VI, or Link to»Pane from the shortcut menu. To link the
reference to a control or indicator within the VI, click or right-click the reference in the
same way and then select the control or indicator to which you want to link from the
shortcut menu.

Use a Property Node or Invoke Node to access the properties and methods for the
control or indicator using a VI Server reference.

If the VI Server reference is associated with a control or indicator, you can right-click
the VI Server reference and select Find Control or Find Indicator from the shortcut
menu to find the associated control or indicator. You also can right-click and select
Find»References to find the associated references. Although you can use VI Server
references with Property Nodes to pass data, you can achieve better performance
through other ways. Try wiring the data directly or using local or global variables
instead before using VI Server references to pass data.

Refer to Comparing References to compare VI Server references.

Note If you place a VI Server reference on a Facade VI and select This VI, the

2392 ni.com
 Functions

VI Server reference returns a reference of type Facade VI.

Inputs/Outputs
• This VI —

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Server\Control

References\Control References.vi

Call Chain Function

Returns the chain of callers from the current VI to the top-level VI. Element 0 of the call
chain array contains the name of the lowest VI in the call chain. Subsequent elements
are callers of the lower VIs in the call chain. The last element of the call chain array is
the name of the top-level VI.

Inputs/Outputs
• call chain —

call chain is the chain of callers from the current VI to the top-level VI.

Get Drag Drop Data Function

Returns drag data from the current drag and drop operation. Only use this function

© National Instruments 2393

 Functions

when it is necessary to access the drag data, not just to examine the data type. If a drag
and drop operation is not in progress, LabVIEW returns an error. If the data requested
is unavailable, LabVIEW returns an error.

Inputs/Outputs
• data name —

data name is the user-defined name of the drag data that you want to retrieve. You also can use
the built-in LabVIEW data types.

LabVIEW Data TypeDefinition

LV_TEXT String
LV_TREE_TAG String
Array of a cluster that contains an array of strings in the item you are
dragging (in order from left to right), an integer that represents the glyph
LV_TREE_ITEMS index associated with the item from which you are dragging data, and an
integer that represents the indent level of the item from which you are
dragging.
Array of a cluster that contains an array of strings in the item you are
LV_LISTBOX_ITEMS dragging (in order from left to right) and an integer that represents the
glyph index associated with the item from which you are dragging data.
LV_PATH Path

• type —

type is the data type of the drag data you want to retrieve.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data is the drag data returned from LabVIEW. data can adapt to any data type.

• error out —

2394 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Structures\Event Structure\Drag and Drop

- Passing Custom Drag Data.vi

Stop Function

Stops the VI in which it executes, just as if you clicked the Abort Execution button on
the toolbar. Before you call this function with a TRUE input, be sure to complete all
final tasks for the VI first, such as closing files, setting safe values for devices being
controlled, and so on.

If you wired the input, stop occurs only if the input value is TRUE. The default is to stop
as soon as the node that is currently executing finishes.

Inputs/Outputs
• stop? (T) —

stop? is the Boolean value that determines if the VI stops.

If you wire an error cluster to stop? and an error occurs, the error cluster passes a TRUE value to
the function.

If you need to abort execution of all VIs in a hierarchy from the block diagram, you can
use this function, but you must use it with caution. If you put this function in a subVI,
you should make its behavior clear to other users of the VI because this function
causes their VI hierarchies to abort execution.

In general, avoid using this function when you have a built-in termination protocol in a

© National Instruments 2395

 Functions

VI. For example, I/O operations should be performed in While Loops so that the VI can
terminate the loop on an I/O error. Also, consider using a front panel stop button
Boolean control to terminate the loop at the request of the user rather than using this
function.

Quit LabVIEW Function

Stops all executing VIs and ends the current instance of LabVIEW.

This function shuts down only LabVIEW. The function does not affect other
applications. The function stops all running VIs the same way the Stop function does. If
there is any unsaved work in memory, you will be prompted to save. Selecting Cancel
will abort the quit.

Inputs/Outputs
• quit? (T) —

If quit? is TRUE (default), LabVIEW quits.

If you wire an error cluster to quit? and an error occurs, the error cluster passes a TRUE value to
the function.

Set Control Values by Index Function

Sets values to the controls for the VI you reference. This function offers better
performance than VI Server objects that write to the terminal of a front panel control,
such as using the Value property in the Control class. However, this function requires
more advanced application design than other methods for setting control values.

2396 ni.com
 Functions

Inputs/Outputs
• VI Refnum —

VI Refnum specifies a reference to the VI for which you want to set multiple control values. You
can wire a strict or non-strict reference to this input. The default is a reference to the current VI.

• control indexes —

control indexes specifies the indexes of the front panel controls for which you want to set
values.

Use the Control Index property in the Control class to retrieve control indexes.
• data values —

data values specifies the values to write to the controls. The default is a variant, but you also can
specify the data type for the values you want to write to the control. To specify a single control,
wire a scalar index to control indexes and wire a single value to data values.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

The Set Control Values by Index function requires that the VI for which you want to set
control values is running or in run mode. Furthermore, the controls for which you want
to set values must have terminals on the block diagram.

Note Because controls nested within clusters or arrays do not have

terminals on the block diagram, you cannot set values for those controls.

This function iterates over the length of the shorter of the two arrays you wire to
control indexes and data values. The function attempts to set all values and does not
stop on the first error. If an error occurs for multiple indices or values, LabVIEW reports
only the first error.

© National Instruments 2397

 Functions

Application Design Considerations

Use the following recommendations to obtain the best performance when you set
control values with this function:

• Retrieve the index of a control only once during an initialization section of an

application.
• To set control values for the current VI, leave VI Refnum unwired.
• Set multiple values in a single call to minimize overhead.
• To set values for a group of controls that have the same data type, wire an array of
that data type to data values. For example, wire an array of 64-bit double-precision
floating point numbers to data values to update a large group of numeric controls
whose representation is 64-bit double-precision, floating point.

Get Control Values by Index Function

Gets values from the controls for the VI you reference. This function offers better
performance than VI Server objects that read from the terminal of a front panel
control, such as using the Value property in the Control class. However, this function
requires more advanced application design than other methods for getting control
values.

Inputs/Outputs
• VI Refnum —

VI Refnum specifies a reference to the VI from which you want to get control values. You can wire
a strict or non-strict reference to this input. The default is a reference to the current VI.

• control indexes —

control indexes specifies an array of indices of front panel controls for which you want to get
values.

Use the Control Index property in the Control class to retrieve control indexes.
• error in (no error) —

2398 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data values —

data values returns the control values.

• error out —

error out contains error information. This output provides standard error out functionality.

The Get Control Values by Index function requires that the VI from which you want to
get control values is running or in run mode. Furthermore, the controls for which you
want to get values must have terminals on the block diagram.

Note Because controls nested within clusters or arrays do not have

terminals on the block diagram, you cannot get values for those controls.

Application Design Considerations

Use the following recommendations to obtain the best performance when you get
control values with this function:

• Retrieve the index of a control only once during an initialization section of an

application.
• To get control values from the current VI, leave VI Refnum unwired.

Palette Editing

You can use the Palette Editing VIs to edit the Controls or Functions palette set
programmatically.

Note The LabVIEW Run-Time Engine does not support the Palette Editing
VIs. Error -4406 occurs if you call the Palette Editing VIs in the LabVIEW
Run-Time Engine.

© National Instruments 2399

 Functions

Palette
Description
Object

Write
Writes palette data to a palette file (.mnu).
Palette

Read
Extracts data from a palette file (.mnu).
Palette

Updates the Controls and Functions palette set programmatically.

Refresh
Palettes This method is similar to the Save Changes button on the Edit Controls and
Functions Palette Set dialog box.

Write Palette

Writes palette data to a palette file (.mnu).

Caution If you use this VI to edit palettes in the labview\menus

directory, LabVIEW does not save the edits in a copy of the original palettes.
After you edit the palettes, you cannot revert to the original palettes.

Inputs/Outputs
• application reference —

application reference is a reference to a target. The default is the local computer. If the target is
not the local computer, you must wire the application reference input to edit the Controls and

2400 ni.com
 Functions

Functions palette set.

Create a project with the target you want to reference. Use the Project:Projects[] property to
obtain the target reference from the project. When you have the target reference, use the
Application property to obtain the application reference.

• palette path —

palette path is the path, including the filename, of the palette file (.mnu). The filename must
have a.mnu extension.

• palette type —

palette type determines whether the palette file (.mnu) contains data for the Controls palette or
Functions palette.

-2 Controls
-1 Functions

• palette data —

palette data contains the data this VI writes to the palette file (.mnu).

• display name —

display name is the name of the palette.

If the selected palette format is Category (Standard) or Category (Icons and Text) and you
move the cursor over the palette icon, display name appears in a tip strip above the palette
icon. If the selected palette format is Icons or Icons and Text and you move the cursor over
the palette icon, display name appears at the top of the palette. If the selected palette
format is Text or Tree, display name appears as text to identify the palette.

• view format —

view format specifies the appearance of the palette items within the selected palette view.
You can select Icons, Text, or Icons and Text.

0 Icons
1 Text

© National Instruments 2401

 Functions

2 Icons and Text

• palette width —

palette width specifies how many palette items can fit in one palette row. palette width
must be greater than or equal to 0. If palette width is less than 0, the VI returns an error.

• items —

items describes the palette items or subpalettes on the palette.

• item path —

item path is the path to the palette item or subpalette. item path accepts all type of
paths. To create an empty slot on the palette, leave item path empty. If item path is
empty, LabVIEW ignores any additional data in the items cluster.

An item is not added to the palette if the item does not exist on your disk. If you still
want to add the item, first ensure that the path provided is valid, and then append
<<file not found>> to the end of the item path.

• library path —

library path (.lvlib) is the path of the library that contains the palette item.

If the library does not exist on your disk, the item is added as a non-library item. If you
still want to add the library item, first ensure that the path provided is valid, and then
append <<file not found>> to the end of the library path.

• use default lvlib palette —

use default lvlib palette configures the VI to use the default project library menu.
LabVIEW ignores this option unless library path (.lvlib) contains a valid path.

• short name —

short name is the abbreviated name of the palette item or subpalette. If the selected
view is Category (Icons and Text) or Icons and Text, short name appears below the
palette item or subpalette.

2402 ni.com
 Functions

• place VI contents —

place VI contents places the VI contents on the block diagram if TRUE. If place VI
contents is FALSE, this VI places only the VI icon on the block diagram.

• hide synchronized item —

hide synchronized item hides the synchronized item if TRUE. hide synchronized item
is valid only if you synchronize this palette with a directory using the synchronize with
directory input.

• reserve spot for synch item —

reserve spot for synch item reserves a spot on the palette for the synchronized item.
This input is valid only if you synchronize this palette with a directory using the
synchronize with directory input.

• configure when placing VI contents —

• 256 color icon —

256 color icon is the 8-bit color icon that signifies the palette item or subpalette.

• B&W color icon —

B&W color icon is the black-and-white icon that signifies the palette item or subpalette.

• help information —

help information determines the help file to which the Context Help window links.

• help tag —

help tag contains the HTML filename or index keyword of the file you want to link to
from the Context Help window.

• help file path —

help file path contains the path or symbolic path to the file you want to link to from the

© National Instruments 2403

 Functions

Context Help window. help file path is either an HTML file or a compiled help file.

• palette description —

palette description contains the text that appears in the Context Help window if you move
the cursor over the subpalette icon in the Controls or Functions palette or if you move the
cursor over an open area of the subpalette.

• synchronize information —

synchronize information contains the synchronization information for the palette file
(.mnu).

• —

synchronize with directory indicates whether the palette file (.mnu) synchronizes with
a directory.

• synchronize directory path —

synchronize directory path indicates the directory path to which LabVIEW

synchronizes the palette file (.mnu). If a palette synchronizes with a directory, the
items you add or delete from the directory automatically appear or disappear on the
palette.

synchronize directory path accepts any type of path when writing the palette file. This
VI ignores synchronize directory path if synchronize with directory is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

2404 ni.com
 Functions

If you have not customized the data in the palette file, use the Read Palette VI to extract
data to the palette file. After you edit the palette data, use the Refresh Palettes method
to update the palettes programmatically.

Note LabVIEW loads a separate palette set for each target. If you write to a
palette set for a specific target without wiring the correct reference to the
target using application reference, the path this VI stores in the palette file
might be incorrect.

Read Palette

Extracts data from a palette file (.mnu).

Use the Write Palette VI to write data to the palette file. After you edit the palette data,
use the Refresh Palettes method to update the palettes programmatically.

Inputs/Outputs
• application reference —

application reference is a reference to a target. The default is the local computer. If the target is
not the local computer, you must wire the application reference input to edit the Controls and
Functions palette set.

Create a project with the target you want to reference. Use the Project:Projects[] property to
obtain the target reference from the project. When you have the target reference, use the
Application property to obtain the application reference.

• palette path —

palette path is the path, including the filename, of the palette file (.mnu). The filename must
have a.mnu extension.

• palette type —

© National Instruments 2405

 Functions

palette type determines whether the palette file (.mnu) contains data for the Controls palette or
Functions palette.

-2 Controls
-1 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• duplicate palette path —

duplicate palette path is the path of the palette file (.mnu) from which the VI reads data.

• palette data —

palette data contains the data the VI reads from the palette file (.mnu).

• display name —

display name is the name of the palette.

If the palette view format is Category (Standard) or Category (Icons and Text) and you
move the cursor over the palette icon, display name appears in a tip strip above the palette
icon. If the selected palette view format is Icons or Icons and Text and you move the cursor
over the palette icon, display name appears at the top of the palette. If the selected palette
view format is Text or Tree, display name appears as text to identify the palette.

• view format —

view format specifies the appearance of the palette items within the selected palette view.

0 Icons
1 Text
2 Icons and Text

• palette width —

palette width specifies how many palette items can fit in one palette row. palette width

2406 ni.com
 Functions

does not have a maximum value. If palette width is less than 0, the VI returns an error.

• items —

items describes the items or subpalettes on the palette.

• item path —

item path is the path to the palette item or subpalette. item path returns an absolute
path when the VI reads the palette file.

If the item does not exist on your disk, the path returns appended with <<file not
found>>. When the full path is not available, the path returns the file name appended
with <<file not found>>. If the palette links to a directory, item path becomes
Folder Name/dir.mnu. If dir.mnu does not exist on your disk, the path returns
appended with <<file not found>>. If the palette item is an empty slot, item
path is empty.

If the palette contains functions or built-in LabVIEW controls and indicators, item path
returns a generic message in the form BUILT_IN_FUNC_**_**_**_***. To
prevent undefined behavior, do not manipulate the generic message the VI returns.

• library path —

library path (.lvlib) is the path of the library that contains the palette item. If the library
item does not exist on your disk, the path returns appended with <<file not
found>>.

• use default lvlib palette —

use default lvlib palette configures the VI to use the default project library menu.
LabVIEW ignores this option unless library path (.lvlib) contains a valid path.

• short name —

short name is the abbreviated name of the palette item or subpalette. If the selected
view is Category (Icons and Text) or Icons and Text, short name appears below the
palette item or subpalette. If the item does not have an abbreviated name, the VI
returns an empty string.

© National Instruments 2407

 Functions

• place VI contents —

place VI contents places the contents of the VI on the block diagram if TRUE. If place VI
contents is FALSE, this VI places only the VI icon on the block diagram.

• hide synchronized item —

hide synchronized item hides the synchronized item if TRUE. If you use the Edit
Controls and Functions Palette Set or the Palette Editing VIs to create a palette file,
then hide synchronized item returns FALSE unless synchronize with directory is TRUE.

• reserve spot for synch item —

reserve spot for synch item reserves a spot on the palette for the synchronized item.

If you use the Edit Controls and Functions Palette Set or the Palette Editing VIs to create
a palette file, then reserve spot for synch item returns FALSE unless synchronize with
directory is TRUE.

• configure when placing VI contents —

• 256 color icon —

256 color icon is the 8-bit color icon that represents the palette item or subpalette.

• B&W color icon —

B&W color icon is the black-and-white icon that represents the palette item or subpalette.

• help information —

help information determines the help file to which the Context Help window links.

• help tag —

help tag contains the HTML filename or index keyword of the file you want to link to
from the Context Help window.

• help file path —

2408 ni.com
 Functions

help file path contains the path or symbolic path to the file you want to link to from the
Context Help window. help file path is either an HTML file or a compiled help file.

• palette description —

palette description contains the text that appears in the Context Help window if you move
the cursor over the subpalette icon in the Controls or Functions palette or if you move the
cursor over an open area of the subpalette.

• synchronize information —

synchronize information contains the synchronization information for the palette file
(.mnu).

• —

synchronize with directory indicates whether the palette file (.mnu) synchronizes with
a directory.

• synchronize directory path —

synchronize directory path indicates the directory path to which LabVIEW

synchronizes the palette file (.mnu). If a palette synchronizes with a directory, the
items you add or delete from the directory automatically appear or disappear on the
palette.

synchronize directory path returns an absolute path when this VI reads the palette file.
This VI ignores synchronize directory path if synchronize with directory is FALSE.

• error out —

error out contains error information. This output provides standard error out functionality.

If you read from a palette set for a specific target without wiring the correct reference
to the target using the application reference input, the paths the VI returns might be
incorrect.

© National Instruments 2409

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\Palette Editing API\

Palette Editing API.lvproj

Refresh Palettes

Updates the Controls and Functions palette set programmatically.

This method is similar to the Save Changes button on the Edit Controls and Functions
Palette Set dialog box.

Refresh Palettes is an Invoke Node with a LabVIEW class of App.

Inputs/Outputs
• reference —

• error in (no error) —

• Palettes:Refresh —

• reference out —

• error out —

• Palettes:Refresh —

CPU Information

Use the CPU Information functions to obtain information on the characteristics of a

computer or target.

2410 ni.com
 Functions

Palette Object Description

CPU Information Function Returns the processor characteristics of the computer.
Number of Cache Levels Function Returns the number of cache levels the computer contains.
Data Cache Size Function Returns the characteristics of the cache level you specify.

CPU Information Function

Returns the processor characteristics of the computer.

Inputs/Outputs
• # of logical processors —

# of logical processors is the number of processing units.

Note This function returns the total number of logical processors, which might be
different from the number currently available to LabVIEW. For example, this function
includes disabled processors in # of logical processors.

• # of packages —

# of packages is the number of packages, or chips. For example, a single hyperthreaded

processor can have two or more logical processors, and a machine with two quad-core
processors has eight logical processors.

• # of cores per package —

# of cores per package is the number of cores each package contains.

• # of logical processors per core —

© National Instruments 2411

 Functions

# of logical processors per core is the number of processing units each core contains.

You can use the following properties to programmatically obtain processor

characteristics from a LabVIEW application running on a remote computer or target
about the system on which the application runs.

• Application:Target:Number of Cores per Package

• Application:Target:Number of Logical Processors
• Application:Target:Number of Logical Processors per Core
• Application:Target:Number of Packages

National Instruments recommends that you use the CPU Information function rather
than these properties to return information from the local computer.

Number of Cache Levels Function

Returns the number of cache levels the computer contains.

Inputs/Outputs
• # of cache levels —

# of cache levels is the number of cache levels.

Data Cache Size Function

Returns the characteristics of the cache level you specify.

2412 ni.com
 Functions

Inputs/Outputs
• cache level (2) —

cache level is the cache level for which to return information. The default is 2.

• total cache size (in bytes) —

total cache size (in bytes) is the size of the cache for the cache level you specify.

• cache entry size (in bytes) —

cache entry size (in bytes) is the size of entries for the cache level you specify.

You can use the Application:Target:Data Cache Entry Sizes and Application:Target:Data
Cache Sizes properties to programmatically obtain information from a LabVIEW
application running on a remote computer or target about the system on which the
application runs.

National Instruments recommends that you use the Data Cache Size function rather
than these properties to return information from the local computer.

Memory Control

Use the Memory Control VIs and functions to improve LabVIEW memory performance.

Palette
Description
Object
New Data
Value Creates a reference to data that you can use to transfer and access the data in a
Reference serialized way.
Function
Delete Data
Removes LabVIEW access to the data that the data value reference or the external
Value
data value reference points to. This function deletes the reference but leaves the data
Reference
intact. Memory leakage might occur if you do not delete the reference.
Function

© National Instruments 2413

 Functions

Palette
Description
Object

Get Memory Returns the amount of physical memory that the LabVIEW process uses. This VI also
Status returns the status of system-wide memory usage.

Swap Values Places the value of the y input into the x' output and the value of the x input into the
Function y' output without allocating memory to perform the operation.
Places the value of Input into a new memory location and returns the value in
Always Copy
Output. Use this function to control the outcome of the LabVIEW compiler buffer
Function
allocation process.
Request
Deallocation Deallocates unused memory after the VI that contains this function runs.
Function

New Data Value Reference Function

Creates a reference to data that you can use to transfer and access the data in a
serialized way.

Inputs/Outputs
• data value —

data value is the data you want the reference to point to. Use the In Place Element structure to
alter the data and the Delete Data Value Reference function to recover the data.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data value reference —

data value reference is the reference that points to the data.

2414 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Data value references contain the same data type of the data they point to. Do not type
cast data value references. However, you can upcast or downcast data value references
that contain LabVIEW classes.

Delete Data Value Reference Function

Removes LabVIEW access to the data that the data value reference or the external data
value reference points to. This function deletes the reference but leaves the data
intact. Memory leakage might occur if you do not delete the reference.

Note You must use this function to delete an external data value reference
and release the associated memory to the device driver that supports and
provides the reference; otherwise, the hardware does not have access to that
buffer space.

Inputs/Outputs
• data value reference —

data value reference points to the data you want to recover. LabVIEW deletes this reference after
you recover the data. Use the New Data Value Reference function to create a data value
reference.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• data value —

© National Instruments 2415

 Functions

data value is the data the reference points to.

• error out —

error out contains error information. This output provides standard error out functionality.

To avoid data copies, leave the data value output of this function unwired when
working with external data value references.

Get Memory Status

Returns the amount of physical memory that the LabVIEW process uses. This VI also
returns the status of system-wide memory usage.

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• total physical memory —

total physical memory returns the total amount of physical memory, in kilobytes, on the
system.

• memory allocated for LabVIEW —

memory allocated for LabVIEW returns the memory size, in kilobytes, allocated for the LabVIEW
process.

• free physical memory —

free physical memory returns the amount of physical memory, in kilobytes, on the system that
is not used.

2416 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

Swap Values Function

Places the value of the y input into the x' output and the value of the x input into the y'
output without allocating memory to perform the operation.

Inputs/Outputs
• y—

y is any data to place in the memory location of the x input.

• ?(T) —

?(T) specifies whether you want to swap the values of the x and y inputs.

• x—

x is any data to place in the memory location of the y input.

• y' —

y' returns the data from the x input.

• x' —

x' returns the data from the y input.

Because this function swaps values without copying data from one place to another,
the function does not consume memory to complete the swap operation. National
Instruments recommends that you use this function to increase value swapping speed
and improve memory utilization efficiency, especially when the data size is large. Visit
ni.com/info and enter the Info Code extnfw for more information about using this

© National Instruments 2417

 Functions

function.

Always Copy Function

Places the value of Input into a new memory location and returns the value in Output.
Use this function to control the outcome of the LabVIEW compiler buffer allocation
process.

Use this function when you want to control the LabVIEW compiler in order to produce
a different result regarding its buffer allocations.

Inputs/Outputs
• Input —

Input is any data to copy to a new location in memory.

• Output —

Output returns the data from Input that LabVIEW copied to a new location in memory.

Request Deallocation Function

Deallocates unused memory after the VI that contains this function runs.

Use this function only for advanced performance optimizations. Deallocating unused
memory can improve performance in some cases. However, aggressively deallocating
memory can cause LabVIEW to reallocate space repeatedly rather than reusing an
allocation. Use this function if your VI allocates a large amount of data but never
reuses that allocation.

2418 ni.com
 Functions

Inputs/Outputs
• flag —

If flag is TRUE, this function deallocates memory after the VI that contains this function runs.

When a top-level VI calls a subVI, LabVIEW allocates a data space of memory in which
that subVI runs. When the subVI finishes running, LabVIEW usually does not deallocate
the data space until the top-level VI finishes running or until the entire application
stops, which can result in out-of-memory conditions and degradation of performance.
Use this function to deallocate the data space immediately after the VI completes
execution.

Place the Request Deallocation function in the subVI you want to deallocate memory
for. When you set the flag Boolean input to TRUE, LabVIEW reduces memory usage by
deallocating the data space for the subVI.

VI Scripting

You can use the VI Scripting VI and functions to create, edit, and run VIs
programmatically.

You must enable VI Scripting to use the VI Scripting VI and functions.

Palette
Description
Object
New VI
Creates and returns a reference to a new VI.
Function
Open VI
Object
Opens a reference to the object whose label you specify with the name/order input.
Reference
Function
New VI Adds a new VI object to the front panel or block diagram of the VI specified by owner
Object refnum and returns a reference to the new object. VI objects include any controls,

© National Instruments 2419

 Functions

Palette
Description
Object
nodes, calls to subVIs, and user-defined controls that you can create in the LabVIEW
Function
editing environment.

New VI
This cluster provides a way to define the location input of the New VI Object function
Object
as an offset from another object. Refer to the New VI Object Location Argument
Offset
example VI in the labview\examples\Application Control\VI
From
Scripting\Creating Objects directory for a visual comparison of the three
Referenced
acceptable types of arguments for the location input.
Object

Searches a target for objects of a particular type and returns an array of references to
Traverse
those objects. The target can be a front panel, a block diagram, or any object that can
for
contain other objects, such as a For Loop, a cluster, or a user-defined control. This VI
GObjects
also recursively finds objects nested within other container objects.

Get
Returns a string containing the label text of the object you specify and a reference to
GObject
that label. This VI returns the same value as the Label.Text property.
Label

Returns an array of class names, in descending order of inheritance, from the top-level
Get Class
class name to the class name you specify. For example, if you specify WhileLoop in
Hierarchy
Class Name this VI returns the array [Generic, Gobject, Node,
from Class
Structure, Loop, WhileLoop]. This VI works for any valid class name,
Name
regardless of whether you have scripting or private functionality turned on or off.

New VI Function

Creates and returns a reference to a new VI.

2420 ni.com
 Functions

Inputs/Outputs
• type specifier VI Refnum (for type only) —

type specifier VI Refnum (for type only) determines the data type of the new VI that this
function returns in vi refnum. If you wire a reference to a pre-existing VI to this parameter,
LabVIEW assigns the data type of that VI to the new VI. Note that LabVIEW does not copy the
contents of the pre-existing VI into the new VI.

If you do not wire data to this input, LabVIEW returns a Generic VI reference for vi refnum.

• options —

options is a bit set that specifies two optional characteristics of the new VI reference that this
function creates. The default is 0x0.

options can be a combination of the following values.

Records VI Server modifications to the new VI created by this function. When you modify
the new VI using VI Server properties or methods, an asterisk (*) appears by the title of the
0x01
VI in its title bar, the list of open VIs displayed in the Window menu, and the All Windows
dialog box. The VI must be in edit mode for LabVIEW to record the modifications.
Prompts user at close. When you attempt to close vi refnum after making changes, LabVIEW
0x04
prompts you to save before closing the VI.

• application refnum —

application refnum is a reference to the LabVIEW application instance in which you want this
function to create the new VI. By default, the function creates the new VI in the same application
instance that called the New VI function. If you wire a reference to a remote application instance
to application refnum, LabVIEW creates the new VI in the remote application instance.

• template —

template is a path to a template VI whose contents you want LabVIEW to copy into the new VI
that this function creates.

When you create a new VI from a template by wiring a path to the template input, you avoid the
need to create each template object individually in the new VI. You can modify small parts of the
code that was copied from the template into the new VI to create a customized version of the
template. To make modifications, you must obtain references to objects in the copied code.
Then you can set properties or invoke methods to change the objects.

• vi type (standard vi) —

© National Instruments 2421

 Functions

vi type specifies the exact type of VI that this function returns as vi refnum. vi type must be at
least as specific as type specifier VI Refnum (for type only).

0 invalid VI type
1 Standard VI (default)
2 Control VI
3 Global VI
4 Polymorphic VI
5 Configuration VI
6 SubSystem
7 Facade VI
8 Method VI
9 Statechart Diagram VI

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• password —

password is the password for the VI specified by the template parameter. If template is not
password protected, LabVIEW ignores password. If template is password protected but you do
not wire password, LabVIEW copies only the parts of the template VI that are not password
protected into the new VI.

• vi refnum —

vi refnum is a reference to the newly created VI. If LabVIEW fails to create a new VI, vi refnum
returns Not A Refnum.

• error out —

error out contains error information. This output provides standard error out functionality.

By default, this function does not show the front panel or block diagram of the VI that
it creates. Although you can inspect or modify the new VI without showing the front
panel or block diagram, you can use the following VI properties and method to display
and position the new VI:

2422 ni.com
 Functions

• Front Panel:Open
• Front Panel Window:Window Bounds
• Block Diagram Window:Open
• Block Diagram Window:Window Bounds
• Block Diagram Window:Origin

Open VI Object Reference Function

Opens a reference to the object whose label you specify with the name/order input.

Inputs/Outputs
• vi object class —

vi object class indicates the class of object whose reference you wish to obtain. To specify a class
type, wire a class specifier constant to this input. A class specifier constant displays a
hierarchical menu that contains the classes of all of the objects in LabVIEW. You can navigate this
hierarchy to find the class of the object you need to reference.

This function also uses vi object class to determine the type of reference returned by object
refnum. For example, if you wire a Boolean-typed Class Specifier Constant to vi object class, the
returned object refnum changes to a Boolean reference.

• owner refnum —

owner refnum is a reference to the owner of the object whose reference you want to obtain. The
owner must be a front panel, a cluster, a block diagram, or a structure diagram. For example, to
obtain a reference for a control on the front panel, wire a reference to the front panel to owner
refnum. Likewise, to obtain a reference for an object inside a For Loop, wire a reference to the
diagram of the For Loop to owner refnum.

• name/order —

name/order indicates the object whose reference you want to obtain. name/order must match
the label of the desired object. If you are obtaining the reference for an object within a cluster,
you can use an array of strings that contain the names of the container hierarchy.

© National Instruments 2423

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• object refnum —

object refnum returns a reference to the object that matches both the class specified by vi
object class and the label specified by name/order. This reference is of the class specified by vi
object class.

• error out —

error out contains error information. This output provides standard error out functionality.

Use the Open VI Object Reference function to obtain a reference to any labeled object
in a target VI. To obtain a reference to an object whose label is not known, you must
navigate to the object from a known reference or use the Traverse for GObjects VI
instead.

Note You cannot use the Open VI Object Reference function to open a
reference to a pane on the front panel. Instead, use the Traverse for GObjects
VI or the Pane[] property to return an array of references to all the panes on
the front panel, and then find the appropriate reference by the name of the
pane.

Block diagram objects do not display a label by default. Because the Open VI Object
Reference function uses the label to locate the desired object, you must display the
label of an object at least once before the function can find the object. You can display
the label of any block diagram object by selecting Visible Items»Label from the
shortcut menu of the object.

If two objects in the target code have the same label, Open VI Object Reference
returns a reference to only one of the two objects. To predictably obtain the desired
object reference, use unique labels for objects of interest in target code.

The Open VI Object Reference function does not search nested objects within the
owner. For example, if you specify a block diagram to be the owner of the object you

2424 ni.com
 Functions

want to find, the Open VI Object Reference function does not search inside of For
Loops on that block diagram. To use the Open VI Object Reference function to obtain a
reference to an object within a For Loop, you must specify the relevant For Loop to be
the owner of the object.

New VI Object Function

Adds a new VI object to the front panel or block diagram of the VI specified by owner
refnum and returns a reference to the new object. VI objects include any controls,
nodes, calls to subVIs, and user-defined controls that you can create in the LabVIEW
editing environment.

Inputs/Outputs
• auto wire? (F) —

auto wire? specifies whether LabVIEW attempts to automatically wire the terminals of the new
object with compatible terminals of the source object wired to location. National Instruments
recommends that you do not use this input. Instead, use VI Scripting to wire the new object to
other objects precisely.

• vi object class —

vi object class indicates the class of the object you want to create. To specify a class, wire a class
specifier constant to this input. A class specifier constant displays a hierarchical menu that
contains the classes of all of the objects in LabVIEW. To identify which class to use for a specific
object, explore the anatomy of common VI objects.

• owner refnum —

owner refnum is a reference to the container into which you want to place the new object. The
most common containers are VIs, clusters, and the diagrams of loops and other structures. For
example, to add a new control to the front panel of a VI, wire a reference to either the relevant VI

© National Instruments 2425

 Functions

or the front panel of the relevant VI to owner refnum. To place a new object inside of a For Loop,
wire a reference to the diagram of the relevant For Loop to owner refnum.

• style —

style indicates the exact kind of object to create. When you create a constant from the style
terminal, you obtain a list of all the objects that are native to LabVIEW. Select a value for style
that is compatible with the class specified by vi object class. For example, you can select the
Round Push Button style if viobject class is Boolean, and you can select the Add style if viobject
class is Function. However, LabVIEW returns a run time error if you select the Add style when
viobject class is Boolean because this pairing is not compatible.

• location —

location specifies where the function places the new object within the container referenced by
owner refnum. The location terminal accepts the following three kinds of arguments:

• Pair of x, y coordinates—LabVIEW places the new object at the given coordinates in relation
to the origin of the owner. To quickly create this type of cluster, create a constant from the
location terminal.
• Reference to a pre-existing object—LabVIEW places the new object next to the referenced
object.
• New VI Object Offset From Referenced Object cluster—LabVIEW places the new object a
specified distance from the object referenced by this cluster.

Refer to the New VI Object Location Argument VI in the Examples section of this topic for a visual
comparison of these argument types.

• Horizontal —

Horizontal is the horizontal position.

• Vertical —

Vertical is the vertical position.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path —

2426 ni.com
 Functions

path is a path to a subVI or pre-existing custom control. Wire data to path only when you want to
add one of these objects to the owner.

• bounds —

bounds specifies the width and height of the new object if the new object is resizable. LabVIEW
ignores bounds for fixed-sized objects.

• Width —

Width specifies the width of the object.

• Height —

Height specifies the height of the object.

• object refnum —

object refnum returns a reference to the new object created by this function. The reference is of
the class specified by vi object class.

• error out —

error out contains error information. This output provides standard error out functionality.

New VI Object Offset From Referenced Object

This cluster provides a way to define the location input of the New VI Object function
as an offset from another object. Refer to the New VI Object Location Argument
example VI in the labview\examples\Application Control\VI
Scripting\Creating Objects directory for a visual comparison of the three
acceptable types of arguments for the location input.

You must initialize the Refnum element to a reference to a pre-existing object by using
the Bundle or Bundle By Name function.

© National Instruments 2427

 Functions

Refnum is a reference to the object next to which you want the New VI Object function to
place a new object.
Relative Direction is the direction relative to the object referenced by Refnum where you
want the new object to be placed.

0 Right
1 Left
2 Top
3 Bottom
4 Top Right
5 Top Left
6 Bottom Right
7 Bottom Left

Point32 indicates the offset of the new object in the given direction from the referenced
object.

Horizontal is the horizontal offset from the location specified by Relative Direction.
Vertical is the vertical offset from the location specified by Relative Direction.

The New VI Object Offset From Referenced Object cluster contains a reference to
another object, an enumerated list of relative directions from that object, and a sub-

2428 ni.com
 Functions

cluster of offset coordinates. Together, the relative direction and offset specify where
the New VI Object function places the new object in relation to the referenced object.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Scripting\

Creating Objects\New VI Object Location Argument.vi

Traverse for GObjects

Searches a target for objects of a particular type and returns an array of references to
those objects. The target can be a front panel, a block diagram, or any object that can
contain other objects, such as a For Loop, a cluster, or a user-defined control. This VI
also recursively finds objects nested within other container objects.

Inputs/Outputs
• Other Refnum —

Other Refnum is a reference to the container object you want to search if you specify the
Traverse Target as Other. The reference must be a VI Server class that inherits from GObject,
FlatSequenceFrame, or Page. LabVIEW ignores this input if Traverse Target is either FP or BD.

• Traverse Target —

Traverse Target indicates the type of container object that you want to traverse. The following
table contains the possible values for this input:

0 FP—Front panel
1 BD—Block diagram
2 Other—Container objects other than the front panel or block diagram. These include structure

© National Instruments 2429

 Functions

diagrams and clusters.

• VI Refnum —

VI Refnum is the reference to the VI you want to traverse. LabVIEW uses this input when Traverse
Target is either FP or BD. LabVIEW ignores this input if you wire a reference to a specific
container object to Other Refnum.

• Class Name —

Class Name is the VI Server class name of the object for which you are searching.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Traverse Generated Code (F) —

Traverse Generated Code specifies whether to traverse code that LabVIEW generates in the
process of implementing certain functions. The default is FALSE.

• dup VI Refnum —

dup VI Refnum returns VI Refnum unchanged.

• References —

References is an array of GObject references to the objects this VI finds. Use the To More Specific
Class function to downcast each reference if necessary.

• # of Refs —

# of Refs is the number of references in the References array.

• error out —

error out contains error information. This output provides standard error out functionality.

To use this VI, specify a Traverse Target of BD for block diagram or FP for front panel
and the Class Name of the object you want to find. To traverse a specific container
object instead of a front panel or block diagram, specify the target as Other and wire

2430 ni.com
 Functions

a reference to the specific object to the Other Refnum input.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Application Control\VI Scripting\Finding

and Modifying Objects\Using Traverse.vi

Get GObject Label

Returns a string containing the label text of the object you specify and a reference to
that label. This VI returns the same value as the Label.Text property.

Inputs/Outputs
• GObject —

GObject specifies the reference to the object whose label you want to get.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• dup GObject —

dup GObject returns the same GObject reference you wire to GObject.

• Object Label —

Object Label returns a string that contains the label text of the object you specify in GObject.
This parameter returns the same value as the Label.Text property.

• Object Has Label? —

© National Instruments 2431

 Functions

Object Has Label? indicates whether the object has a label.

• error out —

error out contains error information. This output provides standard error out functionality.

• Label Reference —

Label Reference returns a reference to the label of the object you specify in GObject.

This VI gets the label text of an object without requiring you to manually cast the
GObject reference to the proper subclass. Instead, this VI attempts to cast the GObject
reference to different LabVIEW subclasses until it casts to the correct one. Once the VI
casts the GObject reference to the proper subclass, the VI returns the Label text and
label reference values for that object.

Get Class Hierarchy from Class Name

Returns an array of class names, in descending order of inheritance, from the top-level
class name to the class name you specify. For example, if you specify WhileLoop in
Class Name this VI returns the array [Generic, Gobject, Node,
Structure, Loop, WhileLoop]. This VI works for any valid class name,
regardless of whether you have scripting or private functionality turned on or off.

This VI works on any class name that you can select in a Class Specifier Constant,
which includes anything under the VI Server class hierarchy except for Application and
VI.

Inputs/Outputs
• Class Name —

Class Name is the VI Server class name of the object for which you want to get a class hierarchy.

• error in (no error) —

2432 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Class Hierarchy —

Class Hierarchy returns an array of class names, in descending order of inheritance, from the
top-level class name to the class name you specify. For example, if you specify WhileLoop in
Class Name this VI returns the array [Generic, Gobject, Node, Structure, Loop,
WhileLoop].

• error out —

error out contains error information. This output provides standard error out functionality.

Application Builder

Use the Application Builder VIs to build, deploy, or clean build specifications.

Palette
Description
Object

Builds a build specification using the properties in memory that you configure when
you right-click a build specification and select Properties. To use this VI, you
Build
previously configure the build specification using the Properties shortcut menu
option.

Deploys the output of a build specification to a target. To use this VI, build the build
Deploy
specification using the Build VI.

Deletes the build specification files that LabVIEW creates during the most recent
Clean
build.

© National Instruments 2433

 Functions

Palette
Description
Object

Get Build Gets the version information of a build specification. This VI returns the Major, Minor,
Specification Fix, and Build version numbers, which correspond to the version numbers on the
Version Version Information page of the properties dialog box for the build specification.

Sets the version information of a build specification. This VI sets the Major, Minor,
Fix, and Build version numbers, which correspond to the version numbers on the
Set Build
Version Information page of the properties dialog box for the build specification.
Specification
LabVIEW saves version information automatically only if you wire a path to this VI.
Version
Therefore, if you wire a project reference to this VI, you must manually save the
project after you set the version information.

Build

Builds a build specification using the properties in memory that you configure when
you right-click a build specification and select Properties. To use this VI, you
previously configure the build specification using the Properties shortcut menu
option.

You cannot use the Build VI with the LabVIEW Run-Time Engine. If you plan to run a
build specification on the LabVIEW Run-Time Engine, do not include the Build VI in any
of the VIs for the build specification.

• Build (path) VI
• Build (project reference) VI

Build (path) VI
Builds a build specification using the properties in memory that you configure when
you right-click a build specification and select Properties. To use this VI, you

2434 ni.com
 Functions

previously configure the build specification using the Properties shortcut menu
option.

You cannot use the Build VI with the LabVIEW Run-Time Engine. If you plan to run a
build specification on the LabVIEW Run-Time Engine, do not include the Build VI in any
of the VIs for the build specification.

Inputs/Outputs
• Path to project —

Path to project specifies the full path to the LabVIEW project (.lvproj) file that contains the
build specification.

• Name of build specification (if empty: build all) —

Name of build specification specifies the name of the build specification. Enter the name that
appears under Build Specifications in the Project Explorer window to specify which build
specification builds. You can change the name of the build specification in the Build
specification name text box on the Information page of the build specification properties dialog
box.

If you do not specify a build specification, the VI builds all build specifications under the
specified target.

• Name of target (My Computer) —

Name of target specifies the target that contains the build specification. The target is My
Computer by default.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Generated files —

© National Instruments 2435

 Functions

Generated files specifies the paths to the generated build files.

• error out —

error out contains error information. This output provides standard error out functionality.

Build (project reference) VI

Builds a build specification using the properties in memory that you configure when
you right-click a build specification and select Properties. To use this VI, you
previously configure the build specification using the Properties shortcut menu
option.

You cannot use the Build VI with the LabVIEW Run-Time Engine. If you plan to run a
build specification on the LabVIEW Run-Time Engine, do not include the Build VI in any
of the VIs for the build specification.

Inputs/Outputs
• Project reference —

Project reference specifies a reference to the LabVIEW project (.lvproj) that contains the
build specification.

• Name of build specification (if empty: build all) —

Name of build specification specifies the name of the build specification. Enter the name that
appears under Build Specifications in the Project Explorer window to specify which build
specification builds. You can change the name of the build specification in the Build
specification name text box on the Information page of the build specification properties dialog
box.

If you do not specify a build specification, the VI builds all build specifications under the

2436 ni.com
 Functions

specified target.

• Name of target (My Computer) —

Name of target specifies the target that contains the build specification. The target is My
Computer by default.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• project ref —

project ref returns a reference to the LabVIEW project that contains the build specification.

• Generated files —

Generated files specifies the paths to the generated build files.

• error out —

error out contains error information. This output provides standard error out functionality.

Deploy

Deploys the output of a build specification to a target. To use this VI, build the build
specification using the Build VI.

Inputs/Outputs
• Path to project —

Path to project specifies the full path to the LabVIEW project (.lvproj) file that contains the
build specification.

© National Instruments 2437

 Functions

• Name of build specification (if empty: deploy all) —

Name of build specification specifies the name of the build specification for the build output
you want to deploy. The name appears under Build Specifications in the Project Explorer
window. You can change the name of the build specification in the Build specification name text
box on the Information page of the build specification properties dialog box.

If you do not specify a build specification, the VI deploys all build specifications to the specified
target.

• Name of target —

Name of target specifies the target to which you want to deploy the build specification output.

You cannot deploy the build specification output to My Computer.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Clean

Deletes the build specification files that LabVIEW creates during the most recent build.

Inputs/Outputs
• Path to project —

Path to project specifies the full path to the LabVIEW project (.lvproj) file that contains the
build specification.

• Name of build specification (if empty: clean all) —

2438 ni.com
 Functions

Name of build specification specifies the name of the build specification. The name appears
under Build Specifications in the Project Explorer window. You can change the name of the
build specification in the Build specification name text box on the Information page of the build
specification properties dialog box.

If you do not specify a build specification, the VI cleans all build specifications under the
specified target.

• Name of target (My Computer) —

Name of target specifies the target that contains the build specification. The target is My
Computer by default.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Get Build Specification Version

Gets the version information of a build specification. This VI returns the Major, Minor,
Fix, and Build version numbers, which correspond to the version numbers on the
Version Information page of the properties dialog box for the build specification.

You can use this VI to get the version information for a stand-alone applications,
installers, .NET interop assemblies, packed libraries, shared libraries, and source
distributions.

Note Installer build specifications contain only Major, Minor, and Fix version
numbers.

This VI returns an error if you attempt to get version information for a zip file.

© National Instruments 2439

 Functions

• Get Build Specification Version (path) VI

• Get Build Specification Version (project reference) VI

The following block diagram displays a common use case of how this VI works with the
Set Build Specification Version VI and Build VI to manage an automatic nightly build
process.

Get Build Specification Version.vi—Gets the Major, Minor, Fix, and Build version numbers after
reading a project path or project reference.
In Place Element Structure—Reads the Major, Minor, Fix, and Build version numbers returned
by the Get Build Specification Version VI and increments only the Build version number.
Set Build Specification Version.vi—Sets the new version information with an incremented
Build number.
Build.vi—Creates the new build output with the new version information.

Get Build Specification Version (path) VI

Gets the version information of a build specification. This VI returns the Major, Minor,
Fix, and Build version numbers, which correspond to the version numbers on the
Version Information page of the properties dialog box for the build specification.

You can use this VI to get the version information for a stand-alone applications,
installers, .NET interop assemblies, packed libraries, shared libraries, and source
distributions.

Note Installer build specifications contain only Major, Minor, and Fix version
numbers.

2440 ni.com
 Functions

This VI returns an error if you attempt to get version information for a zip file.

Inputs/Outputs
• Path to project —

Path to project specifies the full path to the LabVIEW project (.lvproj) file that contains the
build specification.

• Name of build specification —

Name of build specification specifies the name of the build specification for which you want to
get version information. Enter the name that appears under Build Specifications in the Project
Explorer window to retrieve the version information of a build specification.

• Name of target (My Computer) —

Name of target specifies the target that contains the build specification. The target is My
Computer by default.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

• Build Specification Version —

Build Specification Version returns the version information of the build specification.

• Major —

Major specifies the major version. This number may increment to reflect significant feature
changes.

© National Instruments 2441

 Functions

• Minor —

Minor specifies the minor version. Similar to the Major version number, this number may
increment to reflect minor feature changes.

• Fix —

Fix specifies the fix version number. This number may increment for smaller changes, such
as bug fixes.

• Build —

Build specifies the build number. This number may increment to reflect nightly builds.

The following block diagram displays a common use case of how this VI works with the
Set Build Specification Version VI and Build VI to manage an automatic nightly build
process.

Get Build Specification Version.vi—Gets the Major, Minor, Fix, and Build version numbers after
reading a project path or project reference.
In Place Element Structure—Reads the Major, Minor, Fix, and Build version numbers returned
by the Get Build Specification Version VI and increments only the Build version number.
Set Build Specification Version.vi—Sets the new version information with an incremented
Build number.
Build.vi—Creates the new build output with the new version information.

2442 ni.com
 Functions

Get Build Specification Version (project

reference) VI
Gets the version information of a build specification. This VI returns the Major, Minor,
Fix, and Build version numbers, which correspond to the version numbers on the
Version Information page of the properties dialog box for the build specification.

You can use this VI to get the version information for a stand-alone applications,
installers, .NET interop assemblies, packed libraries, shared libraries, and source
distributions.

Note Installer build specifications contain only Major, Minor, and Fix version
numbers.

This VI returns an error if you attempt to get version information for a zip file.

Inputs/Outputs
• Project reference —

Project reference specifies a reference to the LabVIEW project (.lvproj) that contains the
build specification.

• Name of build specification —

Name of build specification specifies the name of the build specification for which you want to
get version information. Enter the name that appears under Build Specifications in the Project
Explorer window to retrieve the version information of a build specification.

• Name of target (My Computer) —

Name of target specifies the target that contains the build specification. The target is My

© National Instruments 2443

 Functions

Computer by default.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• dup Project reference —

dup Project reference returns an unchanged reference to the LabVIEW project that contains the
build specification.

• error out —

error out contains error information. This output provides standard error out functionality.

• Build Specification Version —

Build Specification Version returns the version information of the build specification.

• Major —

Major specifies the major version. This number may increment to reflect significant feature
changes.

• Minor —

Minor specifies the minor version. Similar to the Major version number, this number may
increment to reflect minor feature changes.

• Fix —

Fix specifies the fix version number. This number may increment for smaller changes, such
as bug fixes.

• Build —

Build specifies the build number. This number may increment to reflect nightly builds.

The following block diagram displays a common use case of how this VI works with the
Set Build Specification Version VI and Build VI to manage an automatic nightly build

2444 ni.com
 Functions

process.

Get Build Specification Version.vi—Gets the Major, Minor, Fix, and Build version numbers after
reading a project path or project reference.
In Place Element Structure—Reads the Major, Minor, Fix, and Build version numbers returned
by the Get Build Specification Version VI and increments only the Build version number.
Set Build Specification Version.vi—Sets the new version information with an incremented
Build number.
Build.vi—Creates the new build output with the new version information.

Set Build Specification Version

Sets the version information of a build specification. This VI sets the Major, Minor, Fix,
and Build version numbers, which correspond to the version numbers on the Version
Information page of the properties dialog box for the build specification. LabVIEW
saves version information automatically only if you wire a path to this VI. Therefore, if
you wire a project reference to this VI, you must manually save the project after you set
the version information.

You can use this VI to set the version information for a stand-alone application,
installer, .NET interop assembly, packed library, shared library, or source distribution.

Note Installer build specifications contain only Major, Minor, and Fix version
numbers.

This VI returns an error if you attempt to set version information for a zip file.

© National Instruments 2445

 Functions

• Set Build Specification Version (path) VI

• Set Build Specification Version (project reference) VI

Set Build Specification Version (path) VI

Sets the version information of a build specification. This VI sets the Major, Minor, Fix,
and Build version numbers, which correspond to the version numbers on the Version
Information page of the properties dialog box for the build specification. LabVIEW
saves version information automatically only if you wire a path to this VI. Therefore, if
you wire a project reference to this VI, you must manually save the project after you set
the version information.

You can use this VI to set the version information for a stand-alone application,
installer, .NET interop assembly, packed library, shared library, or source distribution.

Note Installer build specifications contain only Major, Minor, and Fix version
numbers.

This VI returns an error if you attempt to set version information for a zip file.

Inputs/Outputs
• Path to project —

Path to project specifies the full path to the LabVIEW project (.lvproj) file that contains the
build specification.

• Name of build specification —

Name of build specification specifies the name of the build specification for which you want to
set version information. Enter the name that appears under Build Specifications in the Project
Explorer window to set the version information of a build specification.

2446 ni.com
 Functions

• Name of target (My Computer) —

Name of target specifies the target that contains the build specification. The target is My
Computer by default.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Build Specification Version —

Build Specification Version returns the version information of the build specification.

• Major —

Major returns the major version. Increment this number to reflect significant feature
changes.

• Minor —

Minor returns the minor version. Similar to the Major version number, increment this
number to reflect minor feature changes.

• Fix —

Fix returns the fix version number. Increment this number for smaller changes, such as bug
fixes.

• Build —

Build returns the build number. Increment this number for nightly builds.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2447

 Functions

Set Build Specification Version (project

reference) VI
Sets the version information of a build specification. This VI sets the Major, Minor, Fix,
and Build version numbers, which correspond to the version numbers on the Version
Information page of the properties dialog box for the build specification. LabVIEW
saves version information automatically only if you wire a path to this VI. Therefore, if
you wire a project reference to this VI, you must manually save the project after you set
the version information.

You can use this VI to set the version information for a stand-alone application,
installer, .NET interop assembly, packed library, shared library, or source distribution.

Note Installer build specifications contain only Major, Minor, and Fix version
numbers.

This VI returns an error if you attempt to set version information for a zip file.

Inputs/Outputs
• Project reference —

Project reference specifies a reference to the LabVIEW project (.lvproj) that contains the
build specification.

• Name of build specification —

Name of build specification specifies the name of the build specification for which you want to
set version information. Enter the name that appears under Build Specifications in the Project
Explorer window to set the version information of a build specification.

• Name of target (My Computer) —

2448 ni.com
 Functions

Name of target specifies the target that contains the build specification. The target is My
Computer by default.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• Build Specification Version —

Build Specification Version returns the version information of the build specification.

• Major —

Major returns the major version. Increment this number to reflect significant feature
changes.

• Minor —

Minor returns the minor version. Similar to the Major version number, increment this
number to reflect minor feature changes.

• Fix —

Fix returns the fix version number. Increment this number for smaller changes, such as bug
fixes.

• Build —

Build returns the build number. Increment this number for nightly builds.

• dup Project reference —

dup Project reference returns an unchanged reference to the LabVIEW project that contains the
build specification.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2449

 Functions

Report Generation
Use the Report Generation VIs to create and manipulate reports of LabVIEW
applications. You also can use the VIs on this palette to insert text, tables, and graphs
into bookmark locations.

The VIs on this palette can return report generation error codes.

You can use the Report Generation VIs to generate reports that contain VI
documentation or data the VI returns.

Note Some of the VIs on this palette include inputs and outputs the VI
ignores unless you install the Report Generation Toolkit.

Note In some cases, VIs on this palette store graphic files (jpg, png, ...) on the
windows temp folder. Links to these files are used in reports, html files, and
other results. It is not possible to delete the files automatically because it is
uncertain how long the reports are going to be used. It might be necessary to
delete them manually from time to time.

Palette Object Description

Allows you to pass in a block of text along with optional formatting information
Create Easy
and print the report to a designated printer or publish the report to a specified file
Text Report
path.

Print VI Panel
Prints a front panel or VI documentation or saves the front panel or VI
or
documentation to a report.
Documentation

VI
Use the VI Documentation VIs to customize the VI documentation you print or save
Documentation

2450 ni.com
 Functions

Palette Object Description

to a report. VI documentation can include the icon and connector pane, front
panel, block diagram, VI hierarchy, revision history, controls and indicators, and
so on.

Create Report Creates a new report.

Print Report Prints a report to a designated printer or to the default printer on the computer.

Save Report to
Saves an HTML report to the file specified in report file path.
File

Dispose Report Closes the report and releases its interface, which saves memory.

HTML Reports Use the HTML Reports Only VIs to manipulate HTML reports you create in
Only LabVIEW.

Set Report Font Sets the font properties of the report, including those in the headers and footers.

Append Report Appends text to the selected report. Wire data to the text input to determine the
Text polymorphic instance to use or manually select the instance.

Appends a 2D array to a report as a table with the given column width. Wire data
Append Table
to the text data input to determine the polymorphic instance to use or manually
to Report
select the instance.

Append List to
Adds a list of elements to the report.
Report

© National Instruments 2451

 Functions

Palette Object Description

Use the Report Layout VIs to manipulate the layout of reports you create in
Report Layout
LabVIEW.

Append Front Creates an image of the front panel of the VI you specify in VI and appends it to a
Panel Image to report. Wire data to the VI input to determine the polymorphic instance to use or
Report manually select the instance.

Append
Creates an image of the front panel object specified in ctrl reference and appends
Control Image
it to a report.
to Report

For an HTML report, the VI embeds a link to an image into the report.
Append Image
You can wire either a path to the image or a string that contains the image URL to
to Report
this polymorphic VI. Wire data to the path or URL of image input to determine the
polymorphic instance to use or manually select the instance.

Advanced
Use the Advanced Report Generation VIs to manipulate reports you create in
Report
LabVIEW.
Generation

Generates a preformatted report that contains VI documentation, data the VI

Report returns, and report properties, such as the author, company, and number of
pages.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Report Generation\HTML Reports\HTML

Report.vi

2452 ni.com
 Functions

Create Easy Text Report

Allows you to pass in a block of text along with optional formatting information and
print the report to a designated printer or publish the report to a specified file path.

Inputs/Outputs
• font settings —

font settings indicates the font settings a report uses.

• charset (-1) —

charset is the character set to use for report text. The default is -1.

• weight (-1) —

weight is the thickness of the font. The default is -1.

• name —

name is the font name.

• size —

size is the font size.

• print or save? —

print or save? specifies whether the VI prints or saves the report. The default is print. Set this
input to save if you specify a file path in printer name or file path.

© National Instruments 2453

 Functions

print
0
(default)—Prints the report.
save
1
—Saves the report.

• margins —

margins sets the page margins to use when printing the report.

• margins (1.00) —

margins sets the size of the page margins. The default is 1.00 for each margin.

If the margins are smaller than the minimum margins for the printer, the VI returns an error.

• top —

top sets the distance in inches or centimeters between the top of the page and the top
of the content on the page.

• left —

left sets the distance in inches or centimeters between the left edge of the page and the
left edge of the content on the page.

• right —

right sets the distance in inches or centimeters between the right edge of the page and
the right edge of the content on the page.

• bottom —

bottom sets the distance in inches or centimeters between the bottom of the page and
the bottom of the content on the page.

• measurement system (default) —

measurement system sets the units of measurement for the margins.

2454 ni.com
 Functions

0 Default—Sets the margins in the measurement system configured on the computer.

1 US—Sets the margins in inches.
2 Metric—Sets the margins in centimeters.

• text to be printed —

text to be printed is the information you want to include in the report. Any information you want
to include must be in a string.

Note If this string contains printing codes, the VI might not behave as expected. For
example, the string \00 prints a blank page on some computers. If the VI does not
behave as expected, make sure this string does not contain printer codes.

• printer name (default) or file path (dialog) —

printer name or file path is the name of the printer to which you want to print a report or the file
path to which you want to send a report, depending on report type. If you specify a printer
name, the printer must be configured for use with the computer from which you print the report.
If you specify a file path, you must set the print or save? input to save. If you do not wire this
input, the VI uses the default printer in LabVIEW.

If you wire a file path, you must enter the path as a string or use the Path to String function. If you
do not specify a path, LabVIEW displays error -41003.

• report type (HTML) —

report type is the type of report you want to create.

HTML
0
—Creates an HTML report.
Word
1
(Report Generation Toolkit) —Creates a Word report.
Excel
2
(Report Generation Toolkit)—Creates an Excel report.

• orientation (portrait) —

orientation (Windows) specifies how the report appears when it prints.

© National Instruments 2455

 Functions

0 Portrait (default)—Prints the report so the short edge of the paper is the top of the page.
1 Landscape—Prints the report so the long edge of the paper is the top of the page.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• headers —

headers specifies what information appears in the header of each page of the report.

• left —

left is the information you want to appear in the left side of the header.

• center —

center is the information you want to appear in the center portion of the header.

• right —

right is the information you want to appear in the right side of the header.

• footers —

footers specifies what information appears in the footer of each page of the report.

• left —

left is the information you want to appear in the left side of the footer.

• center —

center is the information you want to appear in the center portion of the footer.

• right —

right is the information you want to appear in the right side of the footer.

• error out —

2456 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Use tokens with this VI to generate information in the report, such as in the headers
and footers. For example, you can insert a time stamp in the footers of the report.

You cannot use tokens with Microsoft Word and Excel reports.

You cannot use this VI with any other Report Generation VIs. Also, this VI does not give
you fine-grain control over the formatting of a report. You can use this VI to specify the
text font, set the header and footer, set margins, specify a printer, and set the page
orientation. This VI disposes of the report automatically, which frees memory space.
However, you cannot control where information is placed, append information from
another file, or clear the report of font styles, headers and footers, or text. Use the
other Report Generation VIs to generate complicated reports, such as those with many
different kinds of information.

Print VI Panel or Documentation

Prints a front panel or VI documentation or saves the front panel or VI documentation

to a report.

• Print VI Panel or Documentation (path) VI

• Print VI Panel or Documentation (refnum) VI
• Print VI Panel or Documentation (string) VI

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Print VI
Panel or Documentation VI to create an image of the front panel, the image does not
reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal

© National Instruments 2457

 Functions

on the block diagram of the VI for which you want to create a front panel image.

You also can use the Front Panel:Get Image and Get Panel Image Scaled methods to
return a front panel image programmatically. Use the VI Documentation VIs to print
specific components of VI documentation or to save the components to a report.

Print VI Panel or Documentation (path) VI

Prints a front panel or VI documentation or saves the front panel or VI documentation

to a report.

Inputs/Outputs
• layout options —

layout options sets the page layout and printing options for the report, if report type is Quick
Print. Otherwise, LabVIEW ignores this input.

• orientation (unchanged) —

orientation specifies the page orientation of the report.

You also can use the Printing:Page Orientation property to set the page orientation
programmatically.

0 Unchanged (default)—Uses the default setting for the VI.

1 Portrait—Prints the report so the short edge of the paper is the top of the page.
2 Landscape—Prints the report so the long edge of the paper is the top of the page.

• panel scaling for page (unchanged) —

panel scaling for page sets whether to scale the front panel so it fits on the printed page.

2458 ni.com
 Functions

You also can use the Printing:Front Panel Scaling? property to set the scaling option
programmatically.

0 Unchanged (default)—Uses the default setting for the VI.

1 No Scaling—Does not scale the front panel to fit on the printed page.
2 Scale front panel to fit—Scales the front panel to fit on the printed page.

• margins —

margins sets the page margins of the printed report and the units of measurement for the
margins.

You also can use the Printing:Margins property to set the page margins programmatically.

• override VI margins (false) —

If override VI margins is TRUE, the VI uses the margins you set in margins. If FALSE
(default), the VI uses the default margins for the VI.

• margins (1.00) —

margins sets the size of the page margins. The default is 1.00 for each margin.

If the margins are smaller than the minimum margins for the printer, the VI returns an
error.

• top —

top sets the distance in inches or centimeters between the top of the page and the
top of the content on the page.

• left —

left sets the distance in inches or centimeters between the left edge of the page
and the left edge of the content on the page.

• right —

© National Instruments 2459

 Functions

right sets the distance in inches or centimeters between the right edge of the page
and the right edge of the content on the page.

• bottom —

bottom sets the distance in inches or centimeters between the bottom of the page
and the bottom of the content on the page.

• measurement system (default) —

measurement system sets the units of measurement for the margins.

0 Default—Sets the margins in inches.

1 US—Sets the margins in inches.
2 Metric—Sets the margins in centimeters.

• printer options —

printer options sets the printer to use and the printer options.

The VI uses this input only if report type is 0.

• destination printer name (current) —

destination printer name is the name of the printer to which you want to print the
report.

If you wire a printer name, that printer must be configured for use with the computer
from which you want to print the report.

If you do not wire a printer name, the VI uses the default printer in LabVIEW. The
computer from which you want to print must have a default printer.

You can use the Query Available Printers VI to obtain a list of the printers available on
the computer, including the default printer in LabVIEW.

2460 ni.com
 Functions

• printing method (unchanged) —

printing method sets how LabVIEW prints the report.

This input is similar to the Standard printing, PostScript printing, and Bitmap printing
buttons on the Printing page of the Options dialog box.

You also can use the Printing:Method property to set how LabVIEW prints
programmatically.

0 Unchanged (default)—Uses the default setting for LabVIEW.

1 Standard—Uses standard printing.
2 PostScript—Uses PostScript printing.
3 Bitmap—Uses bitmap printing.

• color or monochrome (unchanged) —

color or monochrome sets whether to send color/grayscale or monochrome output to

the printer.

This input is similar to the Color/Grayscale printing checkbox on the Printing page of
the Options dialog box.

You also can use the Printing:Color/Grayscale? property to configure the colors of the
output programmatically.

0 Unchanged (default)—Uses the default setting for LabVIEW.

Color/grayscale—If the printer is a color printer, LabVIEW sends color output to the
1
printer. Otherwise, LabVIEW sends grayscale output to the printer.
2 Monochrome—Sends monochrome output to the printer.

• page header options —

page header options sets whether to print page headers and configures the contents of the
headers.

• page headers (unchanged) —

© National Instruments 2461

 Functions

page headers sets whether to print page headers for the report.

You also can use the Printing:Page Headers? property to print page headers
programmatically.

Unchanged (default)—Uses the default setting for the VI. If you wire this value, the VI
0
ignores the page header content options input.
Include page headers—Prints headers for the report using the values you wire to the
1
page header content options input.
2 Do not include page headers—Prints no headers for the report.

• page header content options —

page header content options sets which data to include in the page headers.

If page headers is 0, the VI ignores this input.

You also can use the Printing:Header Content properties to customize the contents of
the headers programmatically.

• Include VI Name —

If Include VI Name is TRUE (default), the report headers include the VI name.

• Include VI Path —

If Include VI Path is TRUE (default), the report headers include the VI path.

• Include Last Modification Date —

If Include Last Modification Date is TRUE (default), the report headers include the
last modification date.

• Include Date Printed —

If Include Date Printed is TRUE (default), the report headers include the date
printed.

2462 ni.com
 Functions

• Include Page Number —

If Include Page Number is TRUE (default), the report headers include the page
number.

• Include VI Icon —

If Include VI Icon is TRUE (default), the report headers include the VI icon.

• VI path —

VI path is the path to the VI you want to print or save to a report.

The default is the path to the VI that contains this VI as a subVI.

• contents (complete front panel) —

contents sets which data to print or include in the report.

0 Complete front panel (default)—Prints the entire front panel.

1 Visible portion of front panel—Prints only the currently visible portion of the front panel.
Icon, description, panel and diagram—Prints the VI description, icon and connector pane,
2
front panel, and block diagram.
Documentation: Using the panel—Prints the VI description, front panel, and controls and
3 indicators, including data types, names, and descriptions. LabVIEW prints the controls and
indicators in tabbing order.
Documentation: Using as a subVI—Prints the VI description, icon and connector pane, and
connected controls and indicators, including data types, names, and descriptions. LabVIEW
4
prints the controls and indicators in tabbing order. This format is similar to the format of the VI
and function reference topics in the LabVIEW Help.
Documentation: Complete—Prints the VI description, icon and connector pane, front panel,
5 controls and indicators, including data types, names, and descriptions, block diagram, a list of
subVIs, including icons, names, and paths, revision history information, and the VI hierarchy.
Documentation: Custom—Uses the values you wire to custom contents options to determine
6
which data to print.

• report type (Quick Print) —

© National Instruments 2463

 Functions

report type sets the type of report you want to create.

0 Quick Print (default)—Prints the report immediately.

HTML—Creates an HTML report and returns a reference to it in report out so you can use other
1
Report Generation VIs to customize, save, or print the report.
Word (Report Generation Toolkit)—Creates a report in Word and returns a reference to it in
2
report out so you can use other Report Generation VIs to customize, save, or print the report.
Excel (Report Generation Toolkit)—Creates a report in Excel and returns a reference to it in
3
report out so you can use other Report Generation VIs to customize, save, or print the report.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• custom contents options —

custom contents options sets which data to print or include in the report if you set contents to
Documentation: Custom.

You also can use the Printing:Custom properties to set which data to print programmatically.

• include VI connector and icon —

If include VI connector and icon is TRUE, the report includes the VI icon and connector
pane. The default is FALSE.

• include VI description —

If include VI description is TRUE, the report includes the VI description. The default is
FALSE.

• include front panel —

If include front panel is TRUE, the report includes the front panel. The default is FALSE.

• surround front panel with border —

If surround front panel with border is TRUE, the VI prints a border around the front panel.
The default is FALSE.

• list of controls options —

2464 ni.com
 Functions

list of controls options sets whether to include a list of controls and indicators in the report
and sets the data to include in the list.

• include list of controls —

If include list of controls is TRUE, the report includes a list of controls and indicators.
The default is FALSE.

• list which controls? —

list which controls? sets which controls and indicators to include in the list.

0 all controls (default)—Prints all controls and indicators.

1 connected controls—Prints only connected controls and indicators.

• include control descriptions? —

If include control descriptions? is TRUE, the report includes control and indicator
descriptions. The default is FALSE.

• include control data types? —

If include control data types? is TRUE, the report includes control and indicator data
types. The default is FALSE.

• block diagram options —

block diagram options sets whether to include the block diagram in the report and how to
print structures on the block diagram.

• include block diagram —

If include block diagram is TRUE, the report includes the block diagram. The default is
FALSE.

• hidden frames —

If hidden frames is TRUE, the block diagram image includes all visible subdiagrams of

© National Instruments 2465

 Functions

each Case, Event, and Stacked Sequence structure, followed by all hidden subdiagrams
for each structure. If FALSE (default), the image includes only visible subdiagrams.

• ordered (repeat from higher level if nested) —

If ordered is TRUE, the block diagram image includes all visible subdiagrams of each
Case, Event, and Stacked Sequence structure, followed by all subdiagrams for each
structure in order, including visible and hidden subdiagrams. If FALSE (default), the
image does not repeat visible subdiagrams in the ordered list of subdiagrams.

If Hidden frames is FALSE, the VI ignores this input.

• include VI hierarchy —

If include VI hierarchy is TRUE, the report includes the VI hierarchy. The default is FALSE.

• include list of subVIs —

If include list of subVIs is TRUE, the report includes a list of subVIs, including icons, names,
and paths. The default is FALSE.

• include VI history —

If include VI history is TRUE, the report includes revision history information. The default is
FALSE.

• include Express VI configuration information —

If include Express VI configuration information is TRUE, the report includes configuration

information for any Express VIs on the block diagram. The default is FALSE.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

2466 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Print VI
Panel or Documentation VI to create an image of the front panel, the image does not
reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

You also can use the Front Panel:Get Image and Get Panel Image Scaled methods to
return a front panel image programmatically. Use the VI Documentation VIs to print
specific components of VI documentation or to save the components to a report.

Print VI Panel or Documentation (refnum) VI

Prints a front panel or VI documentation or saves the front panel or VI documentation

to a report.

Inputs/Outputs
• layout options —

layout options sets the page layout and printing options for the report, if report type is Quick
Print. Otherwise, LabVIEW ignores this input.

• orientation (unchanged) —

© National Instruments 2467

 Functions

orientation specifies the page orientation of the report.

You also can use the Printing:Page Orientation property to set the page orientation
programmatically.

0 Unchanged (default)—Uses the default setting for the VI.

1 Portrait—Prints the report so the short edge of the paper is the top of the page.
2 Landscape—Prints the report so the long edge of the paper is the top of the page.

• panel scaling for page (unchanged) —

panel scaling for page sets whether to scale the front panel so it fits on the printed page.

You also can use the Printing:Front Panel Scaling? property to set the scaling option
programmatically.

0 Unchanged (default)—Uses the default setting for the VI.

1 No Scaling—Does not scale the front panel to fit on the printed page.
2 Scale front panel to fit—Scales the front panel to fit on the printed page.

• margins —

margins sets the page margins of the printed report and the units of measurement for the
margins.

You also can use the Printing:Margins property to set the page margins programmatically.

• override VI margins (false) —

If override VI margins is TRUE, the VI uses the margins you set in margins. If FALSE
(default), the VI uses the default margins for the VI.

• margins (1.00) —

margins sets the size of the page margins. The default is 1.00 for each margin.

If the margins are smaller than the minimum margins for the printer, the VI returns an
error.

2468 ni.com
 Functions

• top —

top sets the distance in inches or centimeters between the top of the page and the
top of the content on the page.

• left —

left sets the distance in inches or centimeters between the left edge of the page
and the left edge of the content on the page.

• right —

right sets the distance in inches or centimeters between the right edge of the page
and the right edge of the content on the page.

• bottom —

bottom sets the distance in inches or centimeters between the bottom of the page
and the bottom of the content on the page.

• measurement system (default) —

measurement system sets the units of measurement for the margins.

0 Default—Sets the margins in inches.

1 US—Sets the margins in inches.
2 Metric—Sets the margins in centimeters.

• printer options —

printer options sets the printer to use and the printer options.

The VI uses this input only if report type is 0.

• destination printer name (current) —

© National Instruments 2469

 Functions

destination printer name is the name of the printer to which you want to print the
report.

If you wire a printer name, that printer must be configured for use with the computer
from which you want to print the report.

If you do not wire a printer name, the VI uses the default printer in LabVIEW. The
computer from which you want to print must have a default printer.

You can use the Query Available Printers VI to obtain a list of the printers available on
the computer, including the default printer in LabVIEW.

• printing method (unchanged) —

printing method sets how LabVIEW prints the report.

This input is similar to the Standard printing, PostScript printing, and Bitmap printing
buttons on the Printing page of the Options dialog box.

You also can use the Printing:Method property to set how LabVIEW prints
programmatically.

0 Unchanged (default)—Uses the default setting for LabVIEW.

1 Standard—Uses standard printing.
2 PostScript—Uses PostScript printing.
3 Bitmap—Uses bitmap printing.

• color or monochrome (unchanged) —

color or monochrome sets whether to send color/grayscale or monochrome output to

the printer.

This input is similar to the Color/Grayscale printing checkbox on the Printing page of
the Options dialog box.

You also can use the Printing:Color/Grayscale? property to configure the colors of the
output programmatically.

2470 ni.com
 Functions

0 Unchanged (default)—Uses the default setting for LabVIEW.

Color/grayscale—If the printer is a color printer, LabVIEW sends color output to the
1
printer. Otherwise, LabVIEW sends grayscale output to the printer.
2 Monochrome—Sends monochrome output to the printer.

• page header options —

page header options sets whether to print page headers and configures the contents of the
headers.

• page headers (unchanged) —

page headers sets whether to print page headers for the report.

You also can use the Printing:Page Headers? property to print page headers
programmatically.

Unchanged (default)—Uses the default setting for the VI. If you wire this value, the VI
0
ignores the page header content options input.
Include page headers—Prints headers for the report using the values you wire to the
1
page header content options input.
2 Do not include page headers—Prints no headers for the report.

• page header content options —

page header content options sets which data to include in the page headers.

If page headers is 0, the VI ignores this input.

You also can use the Printing:Header Content properties to customize the contents of
the headers programmatically.

• Include VI Name —

If Include VI Name is TRUE (default), the report headers include the VI name.

© National Instruments 2471

 Functions

• Include VI Path —

If Include VI Path is TRUE (default), the report headers include the VI path.

• Include Last Modification Date —

If Include Last Modification Date is TRUE (default), the report headers include the
last modification date.

• Include Date Printed —

If Include Date Printed is TRUE (default), the report headers include the date
printed.

• Include Page Number —

If Include Page Number is TRUE (default), the report headers include the page
number.

• Include VI Icon —

If Include VI Icon is TRUE (default), the report headers include the VI icon.

• VI reference —

VI reference is a reference to the VI you want to print or save to a report.

You can use the Open VI Reference function to obtain a reference to another VI.

• contents (complete front panel) —

contents sets which data to print or include in the report.

0 Complete front panel (default)—Prints the entire front panel.

1 Visible portion of front panel—Prints only the currently visible portion of the front panel.
Icon, description, panel and diagram—Prints the VI description, icon and connector pane,
2
front panel, and block diagram.

2472 ni.com
 Functions

Documentation: Using the panel—Prints the VI description, front panel, and controls and
3 indicators, including data types, names, and descriptions. LabVIEW prints the controls and
indicators in tabbing order.
Documentation: Using as a subVI—Prints the VI description, icon and connector pane, and
connected controls and indicators, including data types, names, and descriptions. LabVIEW
4
prints the controls and indicators in tabbing order. This format is similar to the format of the VI
and function reference topics in the LabVIEW Help.
Documentation: Complete—Prints the VI description, icon and connector pane, front panel,
5 controls and indicators, including data types, names, and descriptions, block diagram, a list of
subVIs, including icons, names, and paths, revision history information, and the VI hierarchy.
Documentation: Custom—Uses the values you wire to custom contents options to determine
6
which data to print.

• report type (Quick Print) —

report type sets the type of report you want to create.

0 Quick Print (default)—Prints the report immediately.

Standard Report—Creates a report and returns a reference to it in report out so you can use
1
other Report Generation VIs to customize or print the report.
HTML—Creates an HTML report and returns a reference to it in report out so you can use other
2
Report Generation VIs to customize, save, or print the report.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• custom contents options —

custom contents options sets which data to print or include in the report if you set contents to
Documentation: Custom.

You also can use the Printing:Custom properties to set which data to print programmatically.

• include VI connector and icon —

If include VI connector and icon is TRUE, the report includes the VI icon and connector
pane. The default is FALSE.

• include VI description —

© National Instruments 2473

 Functions

If include VI description is TRUE, the report includes the VI description. The default is
FALSE.

• include front panel —

If include front panel is TRUE, the report includes the front panel. The default is FALSE.

• surround front panel with border —

If surround front panel with border is TRUE, the VI prints a border around the front panel.
The default is FALSE.

• list of controls options —

list of controls options sets whether to include a list of controls and indicators in the report
and sets the data to include in the list.

• include list of controls —

If include list of controls is TRUE, the report includes a list of controls and indicators.
The default is FALSE.

• list which controls? —

list which controls? sets which controls and indicators to include in the list.

0 all controls (default)—Prints all controls and indicators.

1 connected controls—Prints only connected controls and indicators.

• include control descriptions? —

If include control descriptions? is TRUE, the report includes control and indicator
descriptions. The default is FALSE.

• include control data types? —

If include control data types? is TRUE, the report includes control and indicator data
types. The default is FALSE.

• block diagram options —

2474 ni.com
 Functions

block diagram options sets whether to include the block diagram in the report and how to
print structures on the block diagram.

• include block diagram —

If include block diagram is TRUE, the report includes the block diagram. The default is
FALSE.

• hidden frames —

If hidden frames is TRUE, the block diagram image includes all visible subdiagrams of
each Case, Event, and Stacked Sequence structure, followed by all hidden subdiagrams
for each structure. If FALSE (default), the image includes only visible subdiagrams.

• ordered (repeat from higher level if nested) —

If ordered is TRUE, the block diagram image includes all visible subdiagrams of each
Case, Event, and Stacked Sequence structure, followed by all subdiagrams for each
structure in order, including visible and hidden subdiagrams. If FALSE (default), the
image does not repeat visible subdiagrams in the ordered list of subdiagrams.

If Hidden frames is FALSE, the VI ignores this input.

• include VI hierarchy —

If include VI hierarchy is TRUE, the report includes the VI hierarchy. The default is FALSE.

• include list of subVIs —

If include list of subVIs is TRUE, the report includes a list of subVIs, including icons, names,
and paths. The default is FALSE.

• include VI history —

If include VI history is TRUE, the report includes revision history information. The default is
FALSE.

• include Express VI configuration information —

If include Express VI configuration information is TRUE, the report includes configuration

© National Instruments 2475

 Functions

information for any Express VIs on the block diagram. The default is FALSE.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Print VI
Panel or Documentation VI to create an image of the front panel, the image does not
reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

You also can use the Front Panel:Get Image and Get Panel Image Scaled methods to
return a front panel image programmatically. Use the VI Documentation VIs to print
specific components of VI documentation or to save the components to a report.

Print VI Panel or Documentation (string) VI

Prints a front panel or VI documentation or saves the front panel or VI documentation

to a report.

2476 ni.com
 Functions

Inputs/Outputs
• layout options —

layout options sets the page layout and printing options for the report, if report type is Quick
Print. Otherwise, LabVIEW ignores this input.

• orientation (unchanged) —

orientation specifies the page orientation of the report.

You also can use the Printing:Page Orientation property to set the page orientation
programmatically.

0 Unchanged (default)—Uses the default setting for the VI.

1 Portrait—Prints the report so the short edge of the paper is the top of the page.
2 Landscape—Prints the report so the long edge of the paper is the top of the page.

• panel scaling for page (unchanged) —

panel scaling for page sets whether to scale the front panel so it fits on the printed page.

You also can use the Printing:Front Panel Scaling? property to set the scaling option
programmatically.

0 Unchanged (default)—Uses the default setting for the VI.

1 No Scaling—Does not scale the front panel to fit on the printed page.
2 Scale front panel to fit—Scales the front panel to fit on the printed page.

• margins —

margins sets the page margins of the printed report and the units of measurement for the
margins.

You also can use the Printing:Margins property to set the page margins programmatically.

• override VI margins (false) —

If override VI margins is TRUE, the VI uses the margins you set in margins. If FALSE
(default), the VI uses the default margins for the VI.

© National Instruments 2477

 Functions

• margins (1.00) —

margins sets the size of the page margins. The default is 1.00 for each margin.

If the margins are smaller than the minimum margins for the printer, the VI returns an
error.

• top —

top sets the distance in inches or centimeters between the top of the page and the
top of the content on the page.

• left —

left sets the distance in inches or centimeters between the left edge of the page
and the left edge of the content on the page.

• right —

right sets the distance in inches or centimeters between the right edge of the page
and the right edge of the content on the page.

• bottom —

bottom sets the distance in inches or centimeters between the bottom of the page
and the bottom of the content on the page.

• measurement system (default) —

measurement system sets the units of measurement for the margins.

0 Default—Sets the margins in inches.

1 US—Sets the margins in inches.
2 Metric—Sets the margins in centimeters.

• printer options —

printer options sets the printer to use and the printer options.

2478 ni.com
 Functions

The VI uses this input only if report type is 0.

• destination printer name (current) —

destination printer name is the name of the printer to which you want to print the
report.

If you wire a printer name, that printer must be configured for use with the computer
from which you want to print the report.

If you do not wire a printer name, the VI uses the default printer in LabVIEW. The
computer from which you want to print must have a default printer.

You can use the Query Available Printers VI to obtain a list of the printers available on
the computer, including the default printer in LabVIEW.

• printing method (unchanged) —

printing method sets how LabVIEW prints the report.

This input is similar to the Standard printing, PostScript printing, and Bitmap printing
buttons on the Printing page of the Options dialog box.

You also can use the Printing:Method property to set how LabVIEW prints
programmatically.

0 Unchanged (default)—Uses the default setting for LabVIEW.

1 Standard—Uses standard printing.
2 PostScript—Uses PostScript printing.
3 Bitmap—Uses bitmap printing.

• color or monochrome (unchanged) —

color or monochrome sets whether to send color/grayscale or monochrome output to

the printer.

This input is similar to the Color/Grayscale printing checkbox on the Printing page of
the Options dialog box.

© National Instruments 2479

 Functions

You also can use the Printing:Color/Grayscale? property to configure the colors of the
output programmatically.

0 Unchanged (default)—Uses the default setting for LabVIEW.

Color/grayscale—If the printer is a color printer, LabVIEW sends color output to the
1
printer. Otherwise, LabVIEW sends grayscale output to the printer.
2 Monochrome—Sends monochrome output to the printer.

• page header options —

page header options sets whether to print page headers and configures the contents of the
headers.

• page headers (unchanged) —

page headers sets whether to print page headers for the report.

You also can use the Printing:Page Headers? property to print page headers
programmatically.

Unchanged (default)—Uses the default setting for the VI. If you wire this value, the VI
0
ignores the page header content options input.
Include page headers—Prints headers for the report using the values you wire to the
1
page header content options input.
2 Do not include page headers—Prints no headers for the report.

• page header content options —

page header content options sets which data to include in the page headers.

If page headers is 0, the VI ignores this input.

You also can use the Printing:Header Content properties to customize the contents of
the headers programmatically.

2480 ni.com
 Functions

• Include VI Name —

If Include VI Name is TRUE (default), the report headers include the VI name.

• Include VI Path —

If Include VI Path is TRUE (default), the report headers include the VI path.

• Include Last Modification Date —

If Include Last Modification Date is TRUE (default), the report headers include the
last modification date.

• Include Date Printed —

If Include Date Printed is TRUE (default), the report headers include the date
printed.

• Include Page Number —

If Include Page Number is TRUE (default), the report headers include the page
number.

• Include VI Icon —

If Include VI Icon is TRUE (default), the report headers include the VI icon.

• VI name —

VI name is the name of the VI you want to print or save to a report. The VI must be in memory.

• contents (complete front panel) —

contents sets which data to print or include in the report.

0 Complete front panel (default)—Prints the entire front panel.

1 Visible portion of front panel—Prints only the currently visible portion of the front panel.

© National Instruments 2481

 Functions

Icon, description, panel and diagram—Prints the VI description, icon and connector pane,
2
front panel, and block diagram.
Documentation: Using the panel—Prints the VI description, front panel, and controls and
3 indicators, including data types, names, and descriptions. LabVIEW prints the controls and
indicators in tabbing order.
Documentation: Using as a subVI—Prints the VI description, icon and connector pane, and
connected controls and indicators, including data types, names, and descriptions. LabVIEW
4
prints the controls and indicators in tabbing order. This format is similar to the format of the VI
and function reference topics in the LabVIEW Help.
Documentation: Complete—Prints the VI description, icon and connector pane, front panel,
5 controls and indicators, including data types, names, and descriptions, block diagram, a list of
subVIs, including icons, names, and paths, revision history information, and the VI hierarchy.
Documentation: Custom—Uses the values you wire to custom contents options to determine
6
which data to print.

• report type (Quick Print) —

report type sets the type of report you want to create.

0 Quick Print (default)—Prints the report immediately.

Excel (Report Generation Toolkit)—Creates a report in Excel and returns a reference to it in
1
report out so you can use other Report Generation VIs to customize, save, or print the report.
Word (Report Generation Toolkit)—Creates a report in Word and returns a reference to it in
2
report out so you can use other Report Generation VIs to customize, save, or print the report.
HTML—Creates an HTML report and returns a reference to it in report out so you can use other
3 Report Generation VIs to customize, save, or print the report. When an HTML report is saved, a
JPEG file is created and saved along with the HTML file.
Standard Report (Windows)—Creates a report and returns a reference to it in report out so you
4
can use other Report Generation VIs to customize or print the report.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• custom contents options —

custom contents options sets which data to print or include in the report if you set contents to
Documentation: Custom.

You also can use the Printing:Custom properties to set which data to print programmatically.

2482 ni.com
 Functions

• include VI connector and icon —

If include VI connector and icon is TRUE, the report includes the VI icon and connector
pane. The default is FALSE.

• include VI description —

If include VI description is TRUE, the report includes the VI description. The default is
FALSE.

• include front panel —

If include front panel is TRUE, the report includes the front panel. The default is FALSE.

• surround front panel with border —

If surround front panel with border is TRUE, the VI prints a border around the front panel.
The default is FALSE.

• list of controls options —

list of controls options sets whether to include a list of controls and indicators in the report
and sets the data to include in the list.

• include list of controls —

If include list of controls is TRUE, the report includes a list of controls and indicators.
The default is FALSE.

• list which controls? —

list which controls? sets which controls and indicators to include in the list.

0 all controls (default)—Prints all controls and indicators.

1 connected controls—Prints only connected controls and indicators.

• include control descriptions? —

If include control descriptions? is TRUE, the report includes control and indicator
descriptions. The default is FALSE.

© National Instruments 2483

 Functions

• include control data types? —

If include control data types? is TRUE, the report includes control and indicator data
types. The default is FALSE.

• block diagram options —

block diagram options sets whether to include the block diagram in the report and how to
print structures on the block diagram.

• include block diagram —

If include block diagram is TRUE, the report includes the block diagram. The default is
FALSE.

• hidden frames —

If hidden frames is TRUE, the block diagram image includes all visible subdiagrams of
each Case, Event, and Stacked Sequence structure, followed by all hidden subdiagrams
for each structure. If FALSE (default), the image includes only visible subdiagrams.

• ordered (repeat from higher level if nested) —

If ordered is TRUE, the block diagram image includes all visible subdiagrams of each
Case, Event, and Stacked Sequence structure, followed by all subdiagrams for each
structure in order, including visible and hidden subdiagrams. If FALSE (default), the
image does not repeat visible subdiagrams in the ordered list of subdiagrams.

If Hidden frames is FALSE, the VI ignores this input.

• include VI hierarchy —

If include VI hierarchy is TRUE, the report includes the VI hierarchy. The default is FALSE.

• include list of subVIs —

If include list of subVIs is TRUE, the report includes a list of subVIs, including icons, names,
and paths. The default is FALSE.

• include VI history —

2484 ni.com
 Functions

If include VI history is TRUE, the report includes revision history information. The default is
FALSE.

• include Express VI configuration information —

If include Express VI configuration information is TRUE, the report includes configuration

information for any Express VIs on the block diagram. The default is FALSE.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Print VI
Panel or Documentation VI to create an image of the front panel, the image does not
reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

You also can use the Front Panel:Get Image and Get Panel Image Scaled methods to
return a front panel image programmatically. Use the VI Documentation VIs to print
specific components of VI documentation or to save the components to a report.

VI Documentation

Use the VI Documentation VIs to customize the VI documentation you print or save to a
report. VI documentation can include the icon and connector pane, front panel, block
diagram, VI hierarchy, revision history, controls and indicators, and so on.

© National Instruments 2485

 Functions

Palette
Description
Object

Append
Creates an image of the front panel of the VI you specify in VI and appends it to a
Front Panel
report. Wire data to the VI input to determine the polymorphic instance to use or
Image to
manually select the instance.
Report

Append VI
Creates an image of the block diagram of the VI you specify in VI and appends the
Block
image to a report. Wire data to the VI input to determine the polymorphic instance
Diagram to
to use or manually select the instance.
Report

Append VI
Appends the description of the VI you specify in VI to a report. Wire data to the VI
Description
input to determine the polymorphic instance to use or manually select the instance.
to Report

Append VI
Appends the icon of the VI you specify in VI to a report. Wire data to the VI input to
Icon to
determine the polymorphic instance to use or manually select the instance.
Report

Append VI
Appends the hierarchy of the VI you specify in VI to a report. Wire data to the VI input
Hierarchy to
to determine the polymorphic instance to use or manually select the instance.
Report

Append VI Appends the revision history of the VI you specify in VI to a report. Wire data to the
History to VI input to determine the polymorphic instance to use or manually select the
Report instance.

Append VI
Appends a list of controls and indicators of the VI you specify in VI to a report. Wire
List of
data to the VI input to determine the polymorphic instance to use or manually select
Controls to
the instance.
Report

Append VI
Appends a list of subVIs of the VI you specify in VI to a report. The list includes subVI
List of SubVIs

2486 ni.com
 Functions

Palette
Description
Object

icons, names, and paths. Wire data to the VI input to determine the polymorphic
to Report
instance to use or manually select the instance.

Append Front Panel Image to Report

Creates an image of the front panel of the VI you specify in VI and appends it to a
report. Wire data to the VI input to determine the polymorphic instance to use or
manually select the instance.

The VI also includes an instance whose connector pane is compatible with versions of
the VI in LabVIEW 6.1 and earlier.

• Append Front Panel Image to Report (path) VI

• Append Front Panel Image to Report (refnum) VI
• Append Front Panel Image to Report (string) VI

For an HTML report, the VI saves the image file to the temporary directory and adds a
link to the image file in the report.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Append
Front Panel Image to Report VI to create an image of the front panel, the image does
not reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

Note If you set Image Format to GIF, the VI does not work when you

© National Instruments 2487

 Functions

include it in a stand-alone application.

You also can use the following methods to return a front panel image
programmatically:

• Front Panel: Get Image

• Front Panel: Get Image Scaled

Append Front Panel Image to Report (path)

VI
Creates an image of the front panel of the VI you specify in VI and appends it to a
report. Wire data to the VI input to determine the polymorphic instance to use or
manually select the instance.

The VI also includes an instance whose connector pane is compatible with versions of
the VI in LabVIEW 6.1 and earlier.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

2488 ni.com
 Functions

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• description —

description is the description of the graphic to display if you open the HTML report in a Web
browser set to display text only.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• visible area only? —

If visible area only? is TRUE, the VI creates an image of only the currently visible portion of the
front panel. The default is FALSE.

• MS Office parameters —

© National Instruments 2489

 Functions

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

2490 ni.com
 Functions

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

For an HTML report, the VI saves the image file to the temporary directory and adds a
link to the image file in the report.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Append
Front Panel Image to Report VI to create an image of the front panel, the image does
not reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

Note If you set Image Format to GIF, the VI does not work when you
include it in a stand-alone application.

You also can use the following methods to return a front panel image
programmatically:

• Front Panel: Get Image

• Front Panel: Get Image Scaled

© National Instruments 2491

 Functions

Append Front Panel Image to Report

(refnum) VI
Creates an image of the front panel of the VI you specify in VI and appends it to a
report. Wire data to the VI input to determine the polymorphic instance to use or
manually select the instance.

The VI also includes an instance whose connector pane is compatible with versions of
the VI in LabVIEW 6.1 and earlier.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT

2492 ni.com
 Functions

3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• description —

description is the description of the graphic to display if you open the HTML report in a Web
browser set to display text only.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• visible area only? —

If visible area only? is TRUE, the VI creates an image of only the currently visible portion of the
front panel. The default is FALSE.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

© National Instruments 2493

 Functions

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

2494 ni.com
 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

For an HTML report, the VI saves the image file to the temporary directory and adds a
link to the image file in the report.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Append
Front Panel Image to Report VI to create an image of the front panel, the image does
not reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

Note If you set Image Format to GIF, the VI does not work when you
include it in a stand-alone application.

You also can use the following methods to return a front panel image
programmatically:

• Front Panel: Get Image

• Front Panel: Get Image Scaled

Append Front Panel Image to Report (string)

VI
Creates an image of the front panel of the VI you specify in VI and appends it to a
report. Wire data to the VI input to determine the polymorphic instance to use or

© National Instruments 2495

 Functions

manually select the instance.

The VI also includes an instance whose connector pane is compatible with versions of
the VI in LabVIEW 6.1 and earlier.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• report in —

2496 ni.com
 Functions

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• description —

description is the description of the graphic to display if you open the HTML report in a Web
browser set to display text only.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• visible area only? —

If visible area only? is TRUE, the VI creates an image of only the currently visible portion of the
front panel. The default is FALSE.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

© National Instruments 2497

 Functions

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

2498 ni.com
 Functions

For an HTML report, the VI saves the image file to the temporary directory and adds a
link to the image file in the report.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Append
Front Panel Image to Report VI to create an image of the front panel, the image does
not reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

Note If you set Image Format to GIF, the VI does not work when you
include it in a stand-alone application.

You also can use the following methods to return a front panel image
programmatically:

• Front Panel: Get Image

• Front Panel: Get Image Scaled

Append VI Block Diagram to Report

Creates an image of the block diagram of the VI you specify in VI and appends the
image to a report. Wire data to the VI input to determine the polymorphic instance to
use or manually select the instance.

Note You cannot include the Append VI Block Diagram to Report VI in a

stand-alone application.

You also can use the Get Diagram Image Scaled method to return a block diagram
image programmatically.

© National Instruments 2499

 Functions

• Append VI Block Diagram to Report (path) VI

• Append VI Block Diagram to Report (refnum) VI
• Append VI Block Diagram to Report (string) VI

Append VI Block Diagram to Report (path) VI

Creates an image of the block diagram of the VI you specify in VI and appends the
image to a report. Wire data to the VI input to determine the polymorphic instance to
use or manually select the instance.

Note You cannot include the Append VI Block Diagram to Report VI in a

stand-alone application.

You also can use the Get Diagram Image Scaled method to return a block diagram
image programmatically.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• hidden frames —

2500 ni.com
 Functions

If hidden frames is TRUE, the block diagram image includes all visible subdiagrams of each
Case, Event, and Stacked Sequence structure, followed by all hidden subdiagrams for each
structure. If FALSE (default), the image includes only visible subdiagrams.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• ordered (repeat from higher level if nested) —

If ordered is TRUE, the block diagram image includes all visible subdiagrams of each Case,
Event, and Stacked Sequence structure, followed by all subdiagrams for each structure in order,
including visible and hidden subdiagrams. If FALSE (default), the image does not repeat visible
subdiagrams in the ordered list of subdiagrams.

© National Instruments 2501

 Functions

If Hidden frames is FALSE, the VI ignores this input.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

2502 ni.com
 Functions

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Block Diagram to Report (refnum)

VI
Creates an image of the block diagram of the VI you specify in VI and appends the
image to a report. Wire data to the VI input to determine the polymorphic instance to
use or manually select the instance.

Note You cannot include the Append VI Block Diagram to Report VI in a

stand-alone application.

You also can use the Get Diagram Image Scaled method to return a block diagram
image programmatically.

© National Instruments 2503

 Functions

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• hidden frames —

If hidden frames is TRUE, the block diagram image includes all visible subdiagrams of each
Case, Event, and Stacked Sequence structure, followed by all hidden subdiagrams for each
structure. If FALSE (default), the image includes only visible subdiagrams.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT

2504 ni.com
 Functions

2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• ordered (repeat from higher level if nested) —

If ordered is TRUE, the block diagram image includes all visible subdiagrams of each Case,
Event, and Stacked Sequence structure, followed by all subdiagrams for each structure in order,
including visible and hidden subdiagrams. If FALSE (default), the image does not repeat visible
subdiagrams in the ordered list of subdiagrams.

If Hidden frames is FALSE, the VI ignores this input.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

© National Instruments 2505

 Functions

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

2506 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Append VI Block Diagram to Report (string)

VI
Creates an image of the block diagram of the VI you specify in VI and appends the
image to a report. Wire data to the VI input to determine the polymorphic instance to
use or manually select the instance.

Note You cannot include the Append VI Block Diagram to Report VI in a

stand-alone application.

You also can use the Get Diagram Image Scaled method to return a block diagram
image programmatically.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• hidden frames —

© National Instruments 2507

 Functions

If hidden frames is TRUE, the block diagram image includes all visible subdiagrams of each
Case, Event, and Stacked Sequence structure, followed by all hidden subdiagrams for each
structure. If FALSE (default), the image includes only visible subdiagrams.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• ordered (repeat from higher level if nested) —

If ordered is TRUE, the block diagram image includes all visible subdiagrams of each Case,
Event, and Stacked Sequence structure, followed by all subdiagrams for each structure in order,
including visible and hidden subdiagrams. If FALSE (default), the image does not repeat visible
subdiagrams in the ordered list of subdiagrams.

2508 ni.com
 Functions

If Hidden frames is FALSE, the VI ignores this input.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

© National Instruments 2509

 Functions

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Description to Report

Appends the description of the VI you specify in VI to a report. Wire data to the VI input
to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Description to Report VI in a stand-

alone application.

• Append VI Description to Report (path) VI

• Append VI Description to Report (refnum) VI
• Append VI Description to Report (string) VI

2510 ni.com
 Functions

Append VI Description to Report (path) VI

Appends the description of the VI you specify in VI to a report. Wire data to the VI input
to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Description to Report VI in a stand-

alone application.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

© National Instruments 2511

 Functions

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

2512 ni.com
 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Description to Report (refnum) VI

Appends the description of the VI you specify in VI to a report. Wire data to the VI input
to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Description to Report VI in a stand-

alone application.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

© National Instruments 2513

 Functions

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

2514 ni.com
 Functions

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Description to Report (string) VI

Appends the description of the VI you specify in VI to a report. Wire data to the VI input
to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Description to Report VI in a stand-

alone application.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

© National Instruments 2515

 Functions

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

2516 ni.com
 Functions

insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Icon to Report

Appends the icon of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note The Append VI Icon to Report VI does not work when you include it in a
stand-alone application.

© National Instruments 2517

 Functions

• Append VI Icon to Report (path) VI

• Append VI Icon to Report (refnum) VI
• Append VI Icon to Report (string) VI

Append VI Icon to Report (path) VI

Appends the icon of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note The Append VI Icon to Report VI does not work when you include it in a
stand-alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to

2518 ni.com
 Functions

the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• caption or alternative string —

caption or alternative string is the text to display instead of the image if you view the report in a
Web browser set to display only text.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from

© National Instruments 2519

 Functions

which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

2520 ni.com
 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Icon to Report (refnum) VI

Appends the icon of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note The Append VI Icon to Report VI does not work when you include it in a
stand-alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.

© National Instruments 2521

 Functions

Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• caption or alternative string —

caption or alternative string is the text to display instead of the image if you view the report in a
Web browser set to display only text.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

2522 ni.com
 Functions

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

© National Instruments 2523

 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Icon to Report (string) VI

Appends the icon of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note The Append VI Icon to Report VI does not work when you include it in a
stand-alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.

2524 ni.com
 Functions

Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• caption or alternative string —

caption or alternative string is the text to display instead of the image if you view the report in a
Web browser set to display only text.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

© National Instruments 2525

 Functions

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

2526 ni.com
 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Hierarchy to Report

Appends the hierarchy of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Hierarchy to Report VI in a stand-

alone application.

• Append VI Hierarchy to Report (path) VI

• Append VI Hierarchy to Report (refnum) VI
• Append VI Hierarchy to Report (string) VI

Append VI Hierarchy to Report (path) VI

Appends the hierarchy of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Hierarchy to Report VI in a stand-

alone application.

© National Instruments 2527

 Functions

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM

2528 ni.com
 Functions

9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

© National Instruments 2529

 Functions

insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Hierarchy to Report (refnum) VI

Appends the hierarchy of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Hierarchy to Report VI in a stand-

alone application.

2530 ni.com
 Functions

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM

© National Instruments 2531

 Functions

9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

2532 ni.com
 Functions

insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI Hierarchy to Report (string) VI

Appends the hierarchy of the VI you specify in VI to a report. Wire data to the VI input to
determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI Hierarchy to Report VI in a stand-

alone application.

© National Instruments 2533

 Functions

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM

2534 ni.com
 Functions

9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

© National Instruments 2535

 Functions

insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI History to Report

Appends the revision history of the VI you specify in VI to a report. Wire data to the VI
input to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI History to Report VI in a stand-alone

application.

2536 ni.com
 Functions

• Append VI History to Report (path) VI

• Append VI History to Report (refnum) VI
• Append VI History to Report (string) VI

Append VI History to Report (path) VI

Appends the revision history of the VI you specify in VI to a report. Wire data to the VI
input to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI History to Report VI in a stand-alone

application.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

© National Instruments 2537

 Functions

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

2538 ni.com
 Functions

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI History to Report (refnum) VI

Appends the revision history of the VI you specify in VI to a report. Wire data to the VI
input to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI History to Report VI in a stand-alone

application.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• error in (no error) —

© National Instruments 2539

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

2540 ni.com
 Functions

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI History to Report (string) VI

Appends the revision history of the VI you specify in VI to a report. Wire data to the VI
input to determine the polymorphic instance to use or manually select the instance.

Note You cannot include the Append VI History to Report VI in a stand-alone

application.

Inputs/Outputs
• report in —

© National Instruments 2541

 Functions

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion

2542 ni.com
 Functions

occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI List of Controls to Report

Appends a list of controls and indicators of the VI you specify in VI to a report. Wire
data to the VI input to determine the polymorphic instance to use or manually select
the instance.

Note You cannot include the Append VI List of Controls to Report VI in a

© National Instruments 2543

 Functions

stand-alone application.

• Append VI List of Controls to Report (path) VI

• Append VI List of Controls to Report (refnum) VI
• Append VI List of Controls to Report (string) VI

Append VI List of Controls to Report (path) VI

Appends a list of controls and indicators of the VI you specify in VI to a report. Wire
data to the VI input to determine the polymorphic instance to use or manually select
the instance.

Note You cannot include the Append VI List of Controls to Report VI in a

stand-alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
1 JPEG

2544 ni.com
 Functions

(default)
2 GIF

• include only controls in con pane? —

If include only controls in con pane? is TRUE, the report includes only connected controls and
indicators. If FALSE (default), the report includes all controls and indicators.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• include control descriptions? —

© National Instruments 2545

 Functions

If include control descriptions? is TRUE, the report includes control and indicator descriptions.
The default is FALSE.

• include control data types? —

If include control data types? is TRUE, the report includes control and indicator data types. The
default is FALSE.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

2546 ni.com
 Functions

insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI List of Controls to Report (refnum)

VI
Appends a list of controls and indicators of the VI you specify in VI to a report. Wire
data to the VI input to determine the polymorphic instance to use or manually select
the instance.

Note You cannot include the Append VI List of Controls to Report VI in a

stand-alone application.

© National Instruments 2547

 Functions

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• include only controls in con pane? —

If include only controls in con pane? is TRUE, the report includes only connected controls and
indicators. If FALSE (default), the report includes all controls and indicators.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT

2548 ni.com
 Functions

2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• include control descriptions? —

If include control descriptions? is TRUE, the report includes control and indicator descriptions.
The default is FALSE.

• include control data types? —

If include control data types? is TRUE, the report includes control and indicator data types. The
default is FALSE.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

© National Instruments 2549

 Functions

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

2550 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Append VI List of Controls to Report (string)

VI
Appends a list of controls and indicators of the VI you specify in VI to a report. Wire
data to the VI input to determine the polymorphic instance to use or manually select
the instance.

Note You cannot include the Append VI List of Controls to Report VI in a

stand-alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• include only controls in con pane? —

If include only controls in con pane? is TRUE, the report includes only connected controls and

© National Instruments 2551

 Functions

indicators. If FALSE (default), the report includes all controls and indicators.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• include control descriptions? —

If include control descriptions? is TRUE, the report includes control and indicator descriptions.
The default is FALSE.

• include control data types? —

If include control data types? is TRUE, the report includes control and indicator data types. The
default is FALSE.

2552 ni.com
 Functions

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

© National Instruments 2553

 Functions

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append VI List of SubVIs to Report

Appends a list of subVIs of the VI you specify in VI to a report. The list includes subVI
icons, names, and paths. Wire data to the VI input to determine the polymorphic
instance to use or manually select the instance.

Note You cannot include the Append VI List of SubVIs to Report VI in a stand-
alone application.

• Append VI List of SubVIs to Report (path) VI

• Append VI List of SubVIs to Report (refnum) VI
• Append VI List of SubVIs to Report (string) VI

Append VI List of SubVIs to Report (path) VI

Appends a list of subVIs of the VI you specify in VI to a report. The list includes subVI
icons, names, and paths. Wire data to the VI input to determine the polymorphic

2554 ni.com
 Functions

instance to use or manually select the instance.

Note You cannot include the Append VI List of SubVIs to Report VI in a stand-
alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is the path to the VI whose image you want to append to the report. The default is the path to
the VI that contains this VI as a subVI.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

© National Instruments 2555

 Functions

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• include Express VI configuration information (F) —

include Express VI configuration information specifies whether the report includes

configuration information for any Express VIs on the block diagram. The default is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

2556 ni.com
 Functions

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI path out —

VI path out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2557

 Functions

Append VI List of SubVIs to Report (refnum)

VI
Appends a list of subVIs of the VI you specify in VI to a report. The list includes subVI
icons, names, and paths. Wire data to the VI input to determine the polymorphic
instance to use or manually select the instance.

Note You cannot include the Append VI List of SubVIs to Report VI in a stand-
alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

VI is a reference to the VI whose data you want to append to the report. The default is a reference
to the VI that contains this VI as a subVI.

2558 ni.com
 Functions

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• include Express VI configuration information (F) —

include Express VI configuration information specifies whether the report includes

configuration information for any Express VIs on the block diagram. The default is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)

© National Instruments 2559

 Functions

correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI out —

VI out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

2560 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Append VI List of SubVIs to Report (string) VI

Appends a list of subVIs of the VI you specify in VI to a report. The list includes subVI
icons, names, and paths. Wire data to the VI input to determine the polymorphic
instance to use or manually select the instance.

Note You cannot include the Append VI List of SubVIs to Report VI in a stand-
alone application.

Inputs/Outputs
• image format (jpeg) —

image format sets the format in which to save the image.

0 PNG
JPEG
1
(default)
2 GIF

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• VI —

© National Instruments 2561

 Functions

VI is the name of the VI whose data you want to append to the report. The default is the name of
the VI that contains this VI as a subVI. The VI must be in memory.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• include Express VI configuration information (F) —

include Express VI configuration information specifies whether the report includes

configuration information for any Express VIs on the block diagram. The default is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

2562 ni.com
 Functions

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• VI name out —

VI name out returns VI unchanged.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

© National Instruments 2563

 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Create Report

Creates a new report.

If you do not use the Create Easy Text Report VI, to create a report, you must use this VI.

Inputs/Outputs
• window state (normal) —

window state (Report Generation Toolkit) sets the Microsoft Word or Excel window to display as
normal, minimized, or maximized. The VI ignores this input for HTML reports.

0 maximized
1 minimized
normal
2
(default)
3 no change

• display alerts? (F) —

display alerts? (Report Generation Toolkit) determines whether prompts and alerts appear in
Microsoft Word or Excel. The default is FALSE, which disables alerts. The VI ignores this input for
HTML reports.

• report type —

2564 ni.com
 Functions

report type is the type of report you want to create.

HTML
0 —Creates an HTML report and returns a reference to it in report out so you can use other
Report Generation VIs to customize, save, or print the report.
Word
1 (Report Generation Toolkit)—Creates a report in Word and returns a reference to it in report
out so you can use other Report Generation VIs to customize, save, or print the report.
Excel
2 (Report Generation Toolkit)—Creates a report in Excel and returns a reference to it in report out
so you can use other Report Generation VIs to customize, save, or print the report.

• template (empty) —

template (Report Generation Toolkit) specifies a path to a Word document or Excel worksheet
that acts as a report template. Enter the path to an existing Word document or Excel worksheet
to open and edit an existing report for a template.

The VI ignores this input for HTML reports.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• machine name (empty) —

machine name (Report Generation Toolkit) specifies a computer from which Microsoft Word or
Excel runs remotely. The VI ignores this input for HTML reports.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2565

 Functions

Print Report

Prints a report to a designated printer or to the default printer on the computer.

If you use this VI to print an HTML report, the computer printing the report must have
Internet Explorer installed.

Note If you use this VI to print a Microsoft Word report and you assign a
printer to the printer name input other than the default system printer,
Microsoft Word resets the default system printer to the printer you assigned
to the printer name input.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• printer name (default) —

printer name is the name of the printer to which you want to print the report.

If you wire a printer name, that printer must be configured for use with the computer from which
you want to print the report. If you do not wire a printer name, the VI uses the default printer for
the computer. The computer from which you want to print must have a default printer.

If you print an HTML report, the VI ignores this input and uses the default printer for Internet
Explorer.

• number of copies (1) —

number of copies specifies how many copies of the report you want to print.

If you do not specify a number, LabVIEW prints one copy.

2566 ni.com
 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Save Report to File

Saves an HTML report to the file specified in report file path.

This VI also saves Microsoft Word and Excel reports.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• report file path —

report file path specifies the path where you want to save the report and the name of the report.

If the path is empty or invalid, the VI returns an error.

• prompt to replace? (F) —

© National Instruments 2567

 Functions

prompt to replace? determines whether the VI displays a dialog box if you specify an existing
filename in report file path. The default is FALSE, which overwrites existing files without
prompting.

This input applies only for HTML reports.

• password ("") —

password (Report Generation Toolkit) creates a read-only report with password protection. You
must enter the password to modify the report.

The VI ignores this input for HTML reports.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Dispose Report

Closes the report and releases its interface, which saves memory.

After the VI runs, you cannot perform further operations on the report. The Dispose
Report VI should be the last VI you use when you create a report.

2568 ni.com
 Functions

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• wait until printing completed? (T) —

wait until printing completed? (Report Generation Toolkit) specifies whether the VI closes the
report if printing is still in progress. The default is TRUE, which specifies to wait to close the
report until the report prints.

The VI ignores this input for HTML, standard, and Excel reports.

• save changes? (F) —

save changes? (Report Generation Toolkit) specifies whether the VI saves changes to the report.
The default is FALSE, which specifies to close the report without saving any changes.

The VI ignores this input if the Close Report input is FALSE. The VI ignores this input for HTML
reports.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• close report? (T) —

close report? (Report Generation Toolkit) specifies whether the VI closes the report. The default
is TRUE, which specifies to close the report file. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

HTML Reports Only

Use the HTML Reports Only VIs to manipulate HTML reports you create in LabVIEW.

The VIs on this palette can return report generation error codes.

© National Instruments 2569

 Functions

Palette Object Description

Append Horizontal
Creates a horizontal rule in an HTML report.
Line to Report

Append Hypertext
Link Anchor to Creates and adds a hypertext link anchor to a HTML report.
Report
Append User
Formatted HTML Inserts text that is not preformatted by LabVIEW in the HTML report.
to Report

Displays an HTML report in the default Web browser. Wire data to the report in
Open HTML Report
input to determine the polymorphic instance to use or manually select the
in Browser
instance.

Append Horizontal Line to Report

Creates a horizontal rule in an HTML report.

This VI also creates a horizontal rule in a Microsoft Word or Excel report.

Inputs/Outputs
• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or

2570 ni.com
 Functions

Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• size (default) —

size sets the height of the horizontal rule.

The default is 1.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.

© National Instruments 2571

 Functions

Use the Create Report VI to generate this LabVIEW class object.

• align (default) —

align aligns the rule on the report.

0 (default)—The VI does not add an ALIGN attribute to the <HR> tag.

1 LEFT
2 CENTER
3 RIGHT

• width (100=default) —

width sets the width of the horizontal rule, either in pixels or as a percentage of the page,
depending on the value you wire to width units.

The default is 100.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• width units —

width units determines whether the width you specify is in pixels or a percentage of the page.

0 Pixels
Percentage
1
(default)

• noshade (F) —

noshade indicates whether to create a solid (TRUE) or three-dimensional (FALSE) horizontal

rule.

If TRUE, the VI adds the noshade attribute to the horizontal rule tag. The default is FALSE.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

2572 ni.com
 Functions

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Report Generation\HTML Reports\HTML

Report.vi

Append Hypertext Link Anchor to Report

Creates and adds a hypertext link anchor to a HTML report.

This VI also creates and adds a hypertext link anchor to a Microsoft Word or Excel
report.

Inputs/Outputs
• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (excel) —

© National Instruments 2573

 Functions

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• URL of link - href —

URL of link - href is the URL of the website or document that you want to link to from the HTML
report.

Use forward slashes (/) to separate directory and filenames in URLs. For example, if you want to
link to report.html in the factory directory on the website www.mycompany.com, use a
URL of http://www.mycompany.com/factory/report.html.

If you link to documents or sites on a local computer, the links might not work if you post the
report on the Web. If you use relative paths in the links and the documents or sites move, the

2574 ni.com
 Functions

links do not work.

• link text —

link text is the text you want to appear as a link in the report.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append User Formatted HTML to Report

Inserts text that is not preformatted by LabVIEW in the HTML report.

Use this VI to insert tags not currently supplied by the Report Generation VIs.

© National Instruments 2575

 Functions

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• HTML text —

HTML text is the text LabVIEW adds to the HTML document without extra tags. This input allows
the use of tags not currently supplied by the Report Generation VIs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Open HTML Report in Browser

Displays an HTML report in the default Web browser. Wire data to the report in input to
determine the polymorphic instance to use or manually select the instance.

If you wire a URL or path that contains a space character to this VI, the VI encodes the
space as %20 before displaying the URL or HTML file in the Web browser.

• Open HTML Report in Browser (Refnum) VI

• Open HTML Report in Browser (Path) VI
• Open HTML Report in Browser (String) VI

2576 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Report Generation\HTML Reports\HTML

Report.vi

Open HTML Report in Browser (Refnum) VI

Displays an HTML report in the default Web browser. Wire data to the report in input to
determine the polymorphic instance to use or manually select the instance.

If you wire a URL or path that contains a space character to this VI, the VI encodes the
space as %20 before displaying the URL or HTML file in the Web browser.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• temporary HTML file created —

temporary HTML file created is the path in which the VI saved the temporary HTML file

© National Instruments 2577

 Functions

containing the report before displaying the HTML file in the Web browser.

After the VI runs, you can delete the temporary HTML file to free disk space.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Report Generation\HTML Reports\HTML

Report.vi

Open HTML Report in Browser (Path) VI

Displays an HTML report in the default Web browser. Wire data to the report in input to
determine the polymorphic instance to use or manually select the instance.

If you wire a URL or path that contains a space character to this VI, the VI encodes the
space as %20 before displaying the URL or HTML file in the Web browser.

Inputs/Outputs
• path —

path is the path to the HTML file you want to display in the default Web browser.

If the path is relative, the VI interprets the path as relative to the application directory, such as
the labview directory or the directory containing the stand-alone application.

• error in (no error) —

2578 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• path out —

path out returns path unchanged.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Report Generation\HTML Reports\HTML

Report.vi

Open HTML Report in Browser (String) VI

Displays an HTML report in the default Web browser. Wire data to the report in input to
determine the polymorphic instance to use or manually select the instance.

If you wire a URL or path that contains a space character to this VI, the VI encodes the
space as %20 before displaying the URL or HTML file in the Web browser.

Inputs/Outputs
• URL —

URL is the URL you want to display in the default Web browser.

For example, wire http://www.site.com/report.html to this input to display the HTML

file report.html on the Web Server www.site.com in the browser.

© National Instruments 2579

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• URL out —

URL out is the URL displayed in the Web browser.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Report Generation\HTML Reports\HTML

Report.vi

Set Report Font

Sets the font properties of the report, including those in the headers and footers.

Inputs/Outputs
• font settings source (VI Inputs) —

font settings source (Report Generation Toolkit) specifies the way in which you want to select
font settings.

The VI ignores this input for HTML reports.

2580 ni.com
 Functions

VI Inputs (default)—The VI uses the values you set in the font settings input. If you do not wire
0
font settings, the VI uses the default font settings of the report class.
1 Font Dialog Box—A dialog box appears that you can use to select font settings.

• text color (unchanged) —

text color is the color of the text in the report.

You can wire a color box constant to this input. The default is T, which leaves the text
unchanged.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• text options —

text options specifies how the text appears in the report.

• Italic —

Italic determines whether subsequent text appears in italics in the report. The default is
Italic Unchanged.

0 Italic Unchanged
1 Italic On
2 Italic Off

• Strike Through —

Strike Through determines whether subsequent text appears with a strikethrough effect in
the report. The default is Strike Through Unchanged.

0 Strike Through Unchanged

1 Strike Through On
2 Strike Through Off

• Underline —

© National Instruments 2581

 Functions

Underline determines whether subsequent text appears underlined in the report. The
default is Underline Unchanged.

0 Underline Unchanged
1 Underline On
2 Underline Off

• Bold —

Bold determines whether subsequent text appears bold in the report. The default is Bold
Unchanged.

0 Bold Unchanged
1 Bold On
2 Bold Off

• font settings —

font settings indicates the font settings a report uses.

• Charset (-1) —

charset is the character set to use for report text. The default is -1.

• Weight (-1) —

weight is the thickness of the font. The default is -1.

• Name —

name is the font name.

• Size —

size is the font size.

• error in (no error) —

2582 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• font out —

font out (Report Generation Toolkit) contains the font settings the VI uses for formatting, which
you can use in other VIs. The values are valid for Microsoft Office reports only.

• font name —

font name indicates the name of the font used, such as Times New Roman.

• font size —

font size indicates the size at which the font appears, in points.

• bold —

bold indicates whether the text is in bold.

• italic —

italic indicates whether the text is in italics.

• underline —

underline indicates whether the text is underlined.

• strike through —

strike through indicates whether the text is struck through.

• font color —

font color indicates the color of the text.

• error out —

© National Instruments 2583

 Functions

error out contains error information. This output provides standard error out functionality.

The available properties include italic, bold, strikethrough, underline, color, font
name, font size, character set, and weight. The font you specify in the VI becomes the
default font for the report.

If you use the Set Report Font VI to set a font in an HTML report, the <font> tag is used
to set the font. This tag remains valid until the end of the file. There is no </font> used.

The table generated by the Append Table to Report VI does not use the font defined by
the Set Report Font VI. The header and body texts of the table have different default
fonts. You can use HTML tags to configure the text font for each cell of the table. Refer
to the example at ni.com for more information about how to generate tables with
different fonts.

Append Report Text

Appends text to the selected report. Wire data to the text input to determine the
polymorphic instance to use or manually select the instance.

The selected report is the one you wire to report in. You can append the text to the
current position of the cursor in the report or on a new line.

• Append Report Text (str wrap) VI

• Append Report Text (num wrap) VI

Append Report Text (str wrap) VI

Appends text to the selected report. Wire data to the text input to determine the
polymorphic instance to use or manually select the instance.

The selected report is the one you wire to report in. You can append the text to the
current position of the cursor in the report or on a new line.

2584 ni.com
 Functions

Inputs/Outputs
• format string (%.3f) —

format string specifies the number formatting to use when LabVIEW converts the numbers to
characters. Use format string when you wire numeric data to the text input.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (excel) —

© National Instruments 2585

 Functions

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• text —

text is the information you want to include in the report.

• append on new line? (F) —

append on new line? appends the information on a new line in the report when set to TRUE.

The default is FALSE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text

2586 ni.com
 Functions

inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append Report Text (num wrap) VI

Appends text to the selected report. Wire data to the text input to determine the
polymorphic instance to use or manually select the instance.

The selected report is the one you wire to report in. You can append the text to the
current position of the cursor in the report or on a new line.

Inputs/Outputs
• format string (%.3f) —

format string specifies the number formatting to use when LabVIEW converts the numbers to
characters. Use format string when you wire numeric data to the text input.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (excel) —

© National Instruments 2587

 Functions

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• text —

text is the information you want to include in the report. Use the format string input to format
the numeric data.

• append on new line? (F) —

append on new line? appends the information on a new line in the report when set to TRUE.

The default is FALSE.

• error in (no error) —

2588 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append Table to Report

Appends a 2D array to a report as a table with the given column width. Wire data to the
text data input to determine the polymorphic instance to use or manually select the
instance.

• Append Text Table to Report (wrap) VI

• Append Numeric Table to Report (wrap) VI

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2589

 Functions

• labview\examples\reports\TextReportExample.llb\Text
Report Example.vi

Append Text Table to Report (wrap) VI

Appends a 2D array to a report as a table with the given column width. Wire data to the
text data input to determine the polymorphic instance to use or manually select the
instance.

Inputs/Outputs
• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

• position (excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (excel) —

2590 ni.com
 Functions

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• measurement system for column width (Default) —

measurement system for column width determines whether the value you enter in column
width is in inches or centimeters.

• column width (1) —

column width defines the width of each column in the report table.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• column headers —

column headers determines how each column is labeled in the table.

• row headers —

row headers determines how each row is labeled in the table.

• text data —

text data is the information you want to be printed in tabular form.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• separate page? (NO) —

separate page? specifies whether to place the table on a new page of the report. The default is

© National Instruments 2591

 Functions

FALSE.

• show grid lines (YES) —

show grid lines specifies whether to display the grid lines of the table. The default is TRUE.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

• range (wd) - start (xl) —

range (wd) - start (xl) (Report Generation Toolkit) indicates the place where the VI inserts the
table.

• start (wd) - row (xl) —

start (wd) - row (xl) is the point where the table begins.

• end (wd) - col (xl) —

end (wd) - col (xl) is the point where the table ends.

• end (xl) —

end (xl) (Report Generation Toolkit) indicates the last cell in the Excel worksheet where the VI
inserts the table.

• row (xl) —

row (xl) is the row number where the table ends.

• col (xl) —

col (xl) is the column number where the table ends.

• error out —

error out contains error information. This output provides standard error out functionality.

2592 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\reports\TextReportExample.llb\Text
Report Example.vi

Append Numeric Table to Report (wrap) VI

Appends a 2D array to a report as a table with the given column width. Wire data to the
text data input to determine the polymorphic instance to use or manually select the
instance.

Inputs/Outputs
• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

© National Instruments 2593

 Functions

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• measurement system for column width (Default) —

measurement system for column width determines whether the value you enter in column
width is in inches or centimeters.

The VI ignores this parameter for HTML reports.

0 US—Sets the column width in inches.

1 Metric—Sets the column width in centimeters.
2 Default (default)—Sets the column width in the measurement system set up on the computer.

• column width (1) —

column width defines the width of each column in the report table.

The value you enter must be in inches or centimeters, depending on the settings you enter in
measurement system for column width. The default is 1. For HTML reports, the VI multiplies the
value by 100 to set the column width in pixels.

2594 ni.com
 Functions

Note If you set column width to a large value and send several columns of data to
the VI, the VI automatically resizes the column width to fit the width of the report on a
single page. If you are using a template and do not want the column width to vary,
use the value -1.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• column headers —

column headers determines how each column is labeled in the table.

• row headers —

row headers determines how each row is labeled in the table.

• numerical data —

numerical data is the numerical information included in the table.

The information must be a 2D array.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• format string (%.3f) —

format string specifies the number formatting to use when converting the numbers to
characters. The default is %.3f.

Use the format string syntax.

• separate page? —

separate page? specifies whether to place the table on a new page of the report. The default is
FALSE.

• show grid lines —

© National Instruments 2595

 Functions

show grid lines specifies whether to display the grid lines of the table. The default is TRUE.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• range (wd) - start (xl) —

range (wd) - start (xl) (Report Generation Toolkit) indicates the place where the VI inserts the
table.

• start (wd) - row (xl) —

start (wd) - row (xl) is the point where the table begins.

• end (wd) - col (xl) —

end (wd) - col (xl) is the point where the table ends.

• end (xl) —

end (xl) (Report Generation Toolkit) indicates the last cell in the Excel worksheet where the VI
inserts the table.

• row (xl) —

row (xl) is the row number where the table ends.

• col (xl) —

col (xl) is the column number where the table ends.

• error out —

error out contains error information. This output provides standard error out functionality.

2596 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\reports\TextReportExample.llb\Text
Report Example.vi

Append List to Report

Adds a list of elements to the report.

Inputs/Outputs
• unordered item type (default) —

unordered item type determines the symbol used to denote a list item in an unordered list. You
can specify a symbol only if the report is HTML-based. The default for HTML-based reports is a
bullet.

0 (default)
1 disc
2 square
3 circle

• ordered item type (default) —

ordered item type determines how the ordered list appears, numerical or alphabetical. The
default is arabic numerals.

0 (default)
1 arabic numerals

© National Instruments 2597

 Functions

2 lower alpha
3 upper alpha

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• list elements —

list elements are the items you want to include in the list.

• list type (ordered) —

list type specifies whether the list appears ordered or unordered in the report.

0 ordered (default)—Presents the list as numerical or alphabetical.

unordered—If the report is HTML-based and you select unordered, you can choose an item
1
indicator.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• ordered start (1) —

ordered start determines the number or letter the list starts with. Enter the number or the letter
that corresponds to the number with which you want to start. For example, A equals 1, B equals
2, or a equals 1, b equals 2. The default is 1.

• bookmark (Word) —

bookmark (Report Generation Toolkit) contains the name of the bookmark in a Microsoft Word
document from which the insertion occurs. The VI ignores this input for HTML reports.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

2598 ni.com
 Functions

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Report Layout

Use the Report Layout VIs to manipulate the layout of reports you create in LabVIEW.

The VIs on this palette can return report generation error codes.

Palette Object Description

Set Report Margins Sets the margins of the specified report.

Set Report Determines whether the report is printed in landscape or portrait

Orientation orientation.

New Report Page Creates a page break within the report.

New Report Line Starts a new line in the report.

Set Report Header

Sets the text of the report header.
Text

© National Instruments 2599

 Functions

Palette Object Description

Set Report Footer Text Sets the text of the report footer.

Set Report Margins

Sets the margins of the specified report.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• margins (1.00) —

margins sets the size of the page margins. The default is 1.00 for each margin.

If the margins are smaller than the minimum margins for the printer, the VI returns an error.

• top —

top sets the distance in inches or centimeters between the top of the page and the top of
the content on the page.

• left —

left sets the distance in inches or centimeters between the left edge of the page and the left
edge of the content on the page.

• right —

right sets the distance in inches or centimeters between the right edge of the page and the

2600 ni.com
 Functions

right edge of the content on the page.

• bottom —

bottom sets the distance in inches or centimeters between the bottom of the page and the
bottom of the content on the page.

• measurement system (default) —

measurement system sets the units of measurement for the margins.

0 Default—Sets the margins in the measurement system configured on the computer.

1 US—Sets the margins in inches.
2 Metric—Sets the margins in centimeters.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• page width (Word) —

page width (Report Generation Toolkit) reports the width of the page after the VI has set the
margins. The VI sets the margins in the units of measurement specified in measurement system.
The VI ignores this input for HTML, standard, or Excel reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Report Orientation

Determines whether the report is printed in landscape or portrait orientation.

© National Instruments 2601

 Functions

You cannot use this VI with HTML reports.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• orientation (portrait) —

orientation (Windows) specifies how the report appears when it prints.

0 Portrait (default)—Prints the report so the short edge of the paper is the top of the page.
1 Landscape—Prints the report so the long edge of the paper is the top of the page.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

New Report Page

Creates a page break within the report.

2602 ni.com
 Functions

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

© National Instruments 2603

 Functions

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

New Report Line

Starts a new line in the report.

This VI has no affect on Excel reports.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• number of lines (1) —

number of lines specifies how many lines the VI adds to the report. The default is 1.

2604 ni.com
 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Report Header Text

Sets the text of the report header.

Header text for Microsoft Excel reports appears only when you print the report.

Use tokens with this VI to generate information in the headers. For example, you can
insert a time stamp in the headers of the report.

You cannot use tokens with Microsoft Word and Excel reports.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• left header text —

© National Instruments 2605

 Functions

left header text is the information you want to appear in the left side of the header.

• center header text —

center header text is the information you want to appear in the center portion of the header.

• right header text —

right header text is the information you want to appear in the right side of the header.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• HTML header size —

HTML header size is the HTML heading tag to use for the header. Use this parameter only for
HTML reports.

0 <H1>
1 <H2>
2 <H3> (default)
3 <H4>
4 <H5>
5 <H6>
6 <H7>

• header placement —

header placement specifies the location of the header.

Note If you insert a header in a Microsoft Word report, the header is added to all
pages regardless of the placement specified.

Top of Document
0
(default)
Append to Body
1
(the header is added to the top of each page)

• report out —

2606 ni.com
 Functions

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Report Footer Text

Sets the text of the report footer.

Use tokens with this VI to generate information in the footers. For example, you can
insert a time stamp in the footers of the report.

You cannot use tokens with Microsoft Word and Excel reports.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• left footer text —

left footer text is the information you want to appear in the left side of the footer.

• center footer text —

center footer text is the information you want to appear in the center portion of the footer.

• right footer text —

© National Instruments 2607

 Functions

right footer text is the information you want to appear in the right side of the footer.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• HTML footer size —

HTML footer size is the HTML heading tag to use for the footer. Use this parameter only for HTML
reports.

0 <H1>
1 <H2>
2 <H3> (default)
3 <H4>
4 <H5>
5 <H6>
6 <H7>

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Append Front Panel Image to Report

Creates an image of the front panel of the VI you specify in VI and appends it to a
report. Wire data to the VI input to determine the polymorphic instance to use or
manually select the instance.

The VI also includes an instance whose connector pane is compatible with versions of
the VI in LabVIEW 6.1 and earlier.

2608 ni.com
 Functions

• Append Front Panel Image to Report (path) VI

• Append Front Panel Image to Report (refnum) VI
• Append Front Panel Image to Report (string) VI

For an HTML report, the VI saves the image file to the temporary directory and adds a
link to the image file in the report.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Append
Front Panel Image to Report VI to create an image of the front panel, the image does
not reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal
on the block diagram of the VI for which you want to create a front panel image.

Note If you set Image Format to GIF, the VI does not work when you
include it in a stand-alone application.

You also can use the following methods to return a front panel image
programmatically:

• Front Panel: Get Image

• Front Panel: Get Image Scaled

Append Control Image to Report

Creates an image of the front panel object specified in ctrl reference and appends it to
a report.

© National Instruments 2609

 Functions

Inputs/Outputs
• image file type (.jpg) —

image file type indicates the format of the image.

0 .jpg (default)
1 .png

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• image depth —

image depth specifies the color depth of the image, which is the number of bits to use to
describe the color of each pixel in the image. Valid values include 1, 4, 8, and 24 bits per pixel.

2610 ni.com
 Functions

image depth affects how LabVIEW interprets the values of image and colors.

• ctrl reference —

ctrl reference is a reference to the control whose image you want to append to the report.

• description —

description is the description of the graphic to display if you open the HTML report in a Web
browser set to display text only.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

© National Instruments 2611

 Functions

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

For an HTML report, the VI saves the image file to the temporary directory and adds a
link to the image file in the report.

If a front panel is not visible, LabVIEW does not update the values in the objects on the
front panel. If you call a VI whose front panel is not visible and you use the Append
Control Image to Report VI to create an image of a front panel object, the image does
not reflect any value changes that occurred when you ran the VI.

If you want the image to reflect value changes, make sure the front panel is open
before any values change. If you do not want to display the front panel but want the
image to reflect value changes, create a Property Node from any front panel terminal

2612 ni.com
 Functions

on the block diagram of the VI for which you want to create a control image.

You also can use the Get Image method to return an image of a front panel object.

Append Image to Report

For an HTML report, the VI embeds a link to an image into the report.

You can wire either a path to the image or a string that contains the image URL to this
polymorphic VI. Wire data to the path or URL of image input to determine the
polymorphic instance to use or manually select the instance.

Note When you append an image to an HTML report, using a file that cannot
be interpreted by the Web browser could make the image unreadable.

• Append Image to Report (path wrap) VI

• Append Image to Report (string wrap) VI

Append Image to Report (path wrap) VI

For an HTML report, the VI embeds a link to an image into the report.

You can wire either a path to the image or a string that contains the image URL to this
polymorphic VI. Wire data to the path or URL of image input to determine the
polymorphic instance to use or manually select the instance.

Note When you append an image to an HTML report, using a file that cannot
be interpreted by the Web browser could make the image unreadable.

© National Instruments 2613

 Functions

Inputs/Outputs
• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

2614 ni.com
 Functions

insertion occurs.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT
2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• path or URL of image —

path or URL of image designates the path to the linked image. If you move the image, you must
update the path.

• caption or alternative string —

caption or alternative string is the text to display instead of the image if you view the report in a
Web browser set to display only text.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

© National Instruments 2615

 Functions

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Append Image to Report (string wrap) VI

For an HTML report, the VI embeds a link to an image into the report.

You can wire either a path to the image or a string that contains the image URL to this
polymorphic VI. Wire data to the path or URL of image input to determine the
polymorphic instance to use or manually select the instance.

Note When you append an image to an HTML report, using a file that cannot
be interpreted by the Web browser could make the image unreadable.

Inputs/Outputs
• MS Office parameters —

2616 ni.com
 Functions

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the
insertion occurs.

• alignment (default) —

alignment sets the alignment of the image in a report. (Report Generation Toolkit) For Microsoft
Word reports, you can use only the LEFT, RIGHT, and MIDDLE options.

0 (default)—The VI does not add an ALIGN attribute to the <IMG> tag.

1 LEFT

© National Instruments 2617

 Functions

2 RIGHT
3 TOP
4 TEXTTOP
5 MIDDLE
6 ABSMIDDLE
7 BASELINE
8 BOTTOM
9 ABSBOTTOM

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• path or URL of image —

path or URL of image designates the URL of the linked image. If you intend to post this page to
the World Wide Web, use forward slashes (/) in paths. If the images are on your local computer or
on a network, use backslashes (\) in the paths. If you move the images, you must update the
links.

• caption or alternative string —

caption or alternative string is the text to display instead of the image if you view the report in a
Web browser set to display only text.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

2618 ni.com
 Functions

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

error out contains error information. This output provides standard error out functionality.

Advanced Report Generation

Use the Advanced Report Generation VIs to manipulate reports you create in LabVIEW.

The VIs on this palette can return report generation error codes.

Palette Object Description

Report Type Returns the report type, such as HTML, of a specified report.

Get Report
Retrieves information about the current font and text settings of a given report.
Settings

Append File to
Appends the text from a text file into the current report.
Report

Clear Report Clears all text, headers, footers, and formatting information from the report.

Clear Report Clears the text and related formatting information from the report. This VI does
Text not affect header and footer information.

Query Available Lists the printers available on the computer, including the default printer in
Printers LabVIEW.

© National Instruments 2619

 Functions

Report Type

Returns the report type, such as HTML, of a specified report.

This VI also returns Microsoft Word or Excel report types.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• report type —

report type indicates the report type.

0 HTML
Word
1
(Report Generation Toolkit)
Excel
2
(Report Generation Toolkit)

• error out —

error out contains error information. This output provides standard error out functionality.

2620 ni.com
 Functions

Get Report Settings

Retrieves information about the current font and text settings of a given report.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• text options —

text options indicates how the text appears in the report.

• Italic —

Italic indicates whether text appears in italics in the report.

• StrikeThrough —

StrikeThrough indicates whether text appears with a strikethrough effect in the report.

• Underline —

© National Instruments 2621

 Functions

Underline indicates whether text appears underlined in the report.

• Bold —

Bold indicates whether text appears bold in the report.

• font settings —

font settings indicates what font settings currently are used in a report.

• charset —

charset is the character set to use for report text. The default is -1.

• name —

name is the font name.

• weight —

weight is the thickness of the font.

• size —

size is the font size.

• error out —

error out contains error information. This output provides standard error out functionality.

• text color —

text color indicates the color of the text in the report.

Append File to Report

Appends the text from a text file into the current report.

The VI appends the text within the report.

2622 ni.com
 Functions

Inputs/Outputs
• MS Office parameters —

MS Office parameters (Report Generation Toolkit) specifies the point in a Microsoft Word or
Excel report where you want an insertion to occur. The VI ignores this input for HTML reports.

You can specify a bookmark in Word or a named range or cell coordinates in Excel. If you set the
report type to Word but do not specify a bookmark, the insertion occurs at the end of the
document.

• position (Excel) —

position contains the row and column coordinates of the point in an Excel worksheet from
which the insertion occurs.

Row and column values in Excel are zero-based, so the row and column coordinates of (0,0)
correspond to cell A1.

• row —

rows specifies the row index.

• column —

columns specifies the column index.

• name (Excel) —

name contains the name of the cell in a Microsoft Excel worksheet from which the insertion
occurs.

• bookmark (Word) —

bookmark contains the name of the bookmark in a Word document from which the

© National Instruments 2623

 Functions

insertion occurs.

• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• file path —

file path is the path of the text file from which you want to pull information into your report.

If the path is empty or invalid, the VI returns an error.

• is spreadsheet file? (Excel) —

is spreadsheet file? (Report Generation Toolkit) embeds a spreadsheet file into the Microsoft
Excel worksheet as a table when set to TRUE. The VI ignores this input for HTML and Word
reports.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• start out (Word) —

start out (Report Generation Toolkit) represents the index of the character at the beginning of
the text inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• end out (Word) —

end out (Report Generation Toolkit) represents the index of the character at the end of the text
inserted in the Microsoft Word document. The VI ignores this input for HTML reports.

• error out —

2624 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Clear Report

Clears all text, headers, footers, and formatting information from the report.

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Clear Report Text

Clears the text and related formatting information from the report. This VI does not
affect header and footer information.

You cannot use this VI with Microsoft Word and Excel reports.

© National Instruments 2625

 Functions

Inputs/Outputs
• report in —

report in is a reference to the report whose appearance, data, and printing you want to control.
Use the Create Report VI to generate this LabVIEW class object.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• report out —

report out is a reference to the report whose appearance, data, and printing you want to control.

You can wire this output to other Report Generation VIs.

• error out —

error out contains error information. This output provides standard error out functionality.

Query Available Printers

Lists the printers available on the computer, including the default printer in LabVIEW.

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• system configured printers —

2626 ni.com
 Functions

system configured printers contains the names of printers available on the computer.

The VI returns the printer names in an array in alphabetical order.

You also can use the Printing:Available Printers property to obtain a list of printer names
programmatically.

• default printer —

default printer is the name of the default printer in LabVIEW.

When you start LabVIEW, the default printer in LabVIEW is the same as the system default printer.
However, any time you print in LabVIEW, the printer you use becomes the default printer in
LabVIEW. LabVIEW no longer recognizes changes to the system default printer until you restart
LabVIEW.

You can use the Printing:Default Printer property to set the default printer in LabVIEW
programmatically.

• error out —

error out contains error information. This output provides standard error out functionality.

Report

Generates a preformatted report that contains VI documentation, data the VI returns,

and report properties, such as the author, company, and number of pages.

Dialog Box Options

Option Description
Report
Contains the following options:
Information

© National Instruments 2627

 Functions

Option Description

• Report title—

Specifies the title of the report.

• Author name—

Specifies the author of the report.

• Company name—

Specifies the name of the company.

• Operator name—

Specifies the name of the operator who generated the data for the report.

• Report print date—

Includes the date of the report.

• Report print time—

Includes the time of the report.

• Page number—

Includes the current page number of the report.

• Total pages—

Includes the total number of pages of the report.

This option prints the total number of pages in the following formats:
◦ (Word 2000, XP, and 2003) Page x of n
◦ (Word 2007) x/n
• VI documentation (appendix)—

Includes the VI documentation in an appendix.

• Comments—

2628 ni.com
 Functions

Option Description

Includes comments to append to the report information.

Contains the following options:

• Title—

Specifies the title for the data.

• Include graph (data input 1)—

Data Input Specifies whether to include a graph with the data.

1
• Y-axis label—

Specifies the label for the y-axis.

• Include table—

Specifies whether to include a table with the data.

Contains the following options:

• Include graph (data input 2)—

Specifies whether to include a graph with the data.

• Title—

Data Input Specifies the title for the data.

2
• Y-axis label—

Specifies the label for the y-axis.

• Include table—

Specifies whether to include a table with the data.

Destination Specifies where to send the report. You can export the report to a Microsoft Word

© National Instruments 2629

 Functions

Option Description

document or a Microsoft Excel worksheet, print to a printer, or save the report in

HTML format for use on a Web page.

Path to
Path where you want to save the report.
save report

Inputs/Outputs
• error in (no error) —

Describes error conditions that occur before this node runs.

• Additional Comments —

Includes additional comments to append to the report information.

• Signal 1 —

Specifies the input signal or signals for Data Input 1.

• Signal 2 —

Specifies the input signal or signals for Data Input 2.

• Enabled? —

Enables or disables the Express VI. The default is TRUE.

• Saved Report Path —

Returns the path where this Express VI saves the report.

• error out —

Contains error information. This output provides standard error out functionality.

Components

Specifies the name of the operator who generated the data for the report.

2630 ni.com
 Functions

Specifies whether to include a table with the data.

Specifies whether to include a graph with the data.

Specifies the label for the y-axis.

Specifies the title for the data.

Specifies whether to include a table with the data.

Specifies whether to include a graph with the data.

Specifies the label for the y-axis.

Specifies the title for the data.

Path where you want to save the report.

Specifies where to send the report. You can export the report to a Microsoft Word
document or a Microsoft Excel worksheet, print to a printer, or save the report in HTML
format for use on a Web page.

Includes comments to append to the report information.

Specifies the name of the company.

Specifies the author of the report.

Includes the VI documentation in an appendix.

Specifies the title of the report.

Specifies the name of the company.

Specifies the author of the report.

Includes the total number of pages of the report.

Includes the current page number of the report.

© National Instruments 2631

 Functions

Specifies the title of the report.

Includes the time of the report.

Includes the date of the report.

Measurement I/O
Use the Measurement I/O VIs and functions to interface with NI-DAQmx and other data
acquisition devices. This palette displays the VIs and functions for the hardware drivers
you install.

If driver VIs you expected to find on this palette are missing, you must install support
for the driver in the current version of LabVIEW.

Note If you installed a driver with a previous version of LabVIEW, you must
reinstall that driver with the current version of LabVIEW. You can search for
National Instrument drivers at NI Drivers and Updates on the National
Instruments Web site or install them using the installation media that
shipped with your purchase.

Palette Object Description

NI Scan Engine Use the NI Scan Engine VIs to interface with the NI Scan Engine.

NI Scan Engine
Use the NI Scan Engine VIs to interface with the NI Scan Engine.

2632 ni.com
 Functions

Palette
Description
Object

Synchronize Synchronizes execution timing to the scan period of the NI Scan Engine. This VI
to Scan waits for each scan to complete and triggers subsequent code to execute once the
Engine scan engine has updated all values.

Get Scan
Engine Returns the scan period of the NI Scan Engine on the target.
Period
Set Scan
Engine Sets the scan period of the NI Scan Engine on the target.
Period

Get Scan
Returns the operating mode of the NI Scan Engine on the target.
Engine Mode

Set Scan
Sets the operating mode of the NI Scan Engine on the target.
Engine Mode

Discovers new I/O modules on any local or networked target. If a local I/O module is
Refresh
detected in a slot that was not previously deployed from a LabVIEW project, this VI
Modules
creates new I/O variables for the I/O module.

Use the Forcing VIs to force and unforce I/O variables programmatically.
Forcing
The VIs on this palette can return general LabVIEW error codes.

Use the Faults VIs to view, set, and clear NI Scan Engine faults programmatically.
Faults
The VIs on this palette can return general LabVIEW error codes.

Fault Use the Fault Configuration VIs to view and configure the level and triggering
Configuration behavior of system faults.

© National Instruments 2633

 Functions

Synchronize to Scan Engine

Synchronizes execution timing to the scan period of the NI Scan Engine. This VI waits
for each scan to complete and triggers subsequent code to execute once the scan
engine has updated all values.

Use the Scan Engine page to configure the scan period. You also can use the Set Scan
Engine Period VI to set the scan period programmatically.

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• scans since last call —

scans since last call returns the number of times the scan engine has completed a scan since the
last call of this VI. You can use this information to identify missed scan iterations and determine
whether the synchronized code consistently finishes executing on time.

• error out —

error out contains error information. This output provides standard error out functionality.

Use this VI for code running outside of a timed structure. For most NI Scan Engine use
cases, NI recommends using a timed structure with the Synchronize to Scan Engine
timing source.

This VI must run on a target with the NI Scan Engine installed.

Examples

Refer to the following example files included with LabVIEW.

2634 ni.com
 Functions

• labview\examples\Scan Engine\Scan Engine.lvproj

Get Scan Engine Period

Returns the scan period of the NI Scan Engine on the target.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• scan period (uSec) —

scan period (uSec) returns the period of the scan engine running on the target.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Scan Engine Period

Sets the scan period of the NI Scan Engine on the target.

Inputs/Outputs
• target address (localhost) —

© National Instruments 2635

 Functions

target address specifies the IP address or DNS name of the target.

• scan period (uSec) —

scan period (uSec) specifies the period for the scan engine running on the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Changing the scan period while the scan engine is running can take a significant
amount of time, and might cause the scan engine to run late, resulting in a major fault.
If changing the scan period results in a fault, you can safely clear the fault after the new
scan period takes effect.

Note If the target includes an expansion I/O driver, you can set the scan
period only when the NI Scan Engine is in Configuration Mode. You can use
the Set Scan Engine Mode VI before this VI to put the NI Scan Engine on the
target into Configuration Mode.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Scan Engine.lvproj

Get Scan Engine Mode

Returns the operating mode of the NI Scan Engine on the target.

2636 ni.com
 Functions

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• mode —

mode returns the operating mode of the NI Scan Engine.

0 Initialization Mode—Occurs only briefly during startup.

1 Configuration Mode—The required mode when configuring scan engine settings.
2 Active Mode—The mode in which the scan engine runs and updates values.
3 Fault Mode—The mode triggered when a major or unrecoverable fault occurs.

• error out —

error out contains error information. This output provides standard error out functionality.

Set Scan Engine Mode

Sets the operating mode of the NI Scan Engine on the target.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• mode (Active Mode) —

© National Instruments 2637

 Functions

mode specifies the operating mode of the scan engine running on the target.

0 Configuration Mode—The required mode when configuring scan engine settings.

1 Active Mode (default)—The mode in which the scan engine runs and updates values.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Refresh Modules

Discovers new I/O modules on any local or networked target. If a local I/O module is
detected in a slot that was not previously deployed from a LabVIEW project, this VI
creates new I/O variables for the I/O module.

These automatically-created I/O variables use the default I/O variable settings. This VI
does not add the new I/O variables to a LabVIEW project, and the new I/O variables do
not persist when the target restarts.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

2638 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

If you physically change an I/O module deployed from a LabVIEW project, this VI
cannot overwrite the deployed configuration until you undeploy the I/O module in the
LabVIEW project. However, if you physically change an I/O module that was
automatically detected by this VI or the corresponding Refresh Local Modules button
in the NI Distributed System Manager, this VI adds and deletes automatically-created
I/O variables to match the new physical configuration.

Forcing

Use the Forcing VIs to force and unforce I/O variables programmatically.

The VIs on this palette can return general LabVIEW error codes.

Palette
Description
Object
Enable
Variable Enables forcing for I/O variables and I/O aliases on the target.
Forcing

Disable
Disables forcing for I/O variables and I/O aliases on the target. Unless you clear
Variable
forcing, the previous forced values return when you re-enable forcing.
Forcing

Clear
Variable Unforces all currently forced I/O variables and I/O aliases on the target.
Forcing

Force Forces an I/O variable or I/O alias to assume forced value until you disable forcing,
Variable reboot the target, or force the variable to assume a new forced value.

© National Instruments 2639

 Functions

Palette
Description
Object

Unforce Discontinues forcing on an I/O variable or I/O alias and returns control of the I/O
Variable value to the NI Scan Engine.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Programmatic Forcing.lvproj

Enable Variable Forcing

Enables forcing for I/O variables and I/O aliases on the target.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Forcing must be enabled on the target for individual I/O variable or I/O alias forces to
take effect. This VI affects the equivalent of a master switch for all I/O variable and I/O
alias forcing on the target.

2640 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Programmatic Forcing.lvproj

Disable Variable Forcing

Disables forcing for I/O variables and I/O aliases on the target. Unless you clear forcing,
the previous forced values return when you re-enable forcing.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Forcing must be enabled on the target for individual I/O variable or I/O alias forces to
take effect. Use the Enable Variable Forcing VI to re-enable forcing on the target.

Clear Variable Forcing

Unforces all currently forced I/O variables and I/O aliases on the target.

© National Instruments 2641

 Functions

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

This VI does not disable forcing on the target. Use the Disable Variable Forcing VI to
prevent I/O variable and I/O alias forcing from taking effect on the target.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Programmatic Forcing.lvproj

Force Variable

Forces an I/O variable or I/O alias to assume forced value until you disable forcing,
reboot the target, or force the variable to assume a new forced value.

Inputs/Outputs
• variable path (URL) —

2642 ni.com
 Functions

variable path (URL) specifies the path to the I/O variable or I/O alias. The path can be absolute
or relative. The format of the variable path is
\\<TargetName>\<ModuleName>\<VariableName>. You can view the variable path for
an I/O variable in the Context Help window when you hover over the I/O variable node on the
block diagram.

• forced value —

forced value is the value for the I/O variable or I/O alias to assume while forcing is enabled on
the target and the enable forcing input of this VI is TRUE.

To ensure data integrity, you must wire a value of the same data type as the I/O variable. To
verify the data type of an I/O variable, right-click the I/O variable in the Project Explorer window
and select Properties to display the Shared Variable Properties dialog box.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

To perform batch forcing on a set of I/O variables, disable forcing on the target, force
each I/O variable, then enable forcing on the target.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Programmatic Forcing.lvproj

Unforce Variable

Discontinues forcing on an I/O variable or I/O alias and returns control of the I/O value
to the NI Scan Engine.

© National Instruments 2643

 Functions

Inputs/Outputs
• variable path (URL) —

variable path (URL) specifies the path to the I/O variable or I/O alias. The path can be absolute
or relative. The format of the variable path is
\\<TargetName>\<ModuleName>\<VariableName>. You can view the variable path for
an I/O variable in the Context Help window when you hover over the I/O variable node on the
block diagram.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Programmatic Forcing.lvproj

Faults

Use the Faults VIs to view, set, and clear NI Scan Engine faults programmatically.

The VIs on this palette can return general LabVIEW error codes.

2644 ni.com
 Functions

Palette
Description
Object
Get
Fault Returns a list of active faults.
List

Set Creates a fault. When the major fault input is TRUE, this VI triggers fault mode. Use the
Fault code element of the error in (user fault) input cluster to specify the fault code.

Clear Clears NI Scan Engine faults. If the fault you specify using the fault code input is active, this
Fault VI clears the fault. If the fault is not active, this VI takes no action and generates no error.

Clear
All Clears all active faults on the target.
Faults

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Scan Engine.lvproj

Get Fault List

Returns a list of active faults.

Inputs/Outputs
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• fault list —

© National Instruments 2645

 Functions

fault list contains the list of active faults.

• code —

code is the fault code.

• level —

level is the severity level of the fault.

• first reported time —

first reported time returns the time the fault first occurred since it was last cleared.

• number reported —

number reported is the number of times the fault has occurred since it was last cleared.

• error out —

error out contains error information. This output provides standard error out functionality.

This VI allocates memory and can affect the determinism of the application. This VI
must run on a target with the NI Scan Engine installed.

To obtain the fault list of a remote target from a host computer, you can use the
DataSocket Read VI to subscribe to the following URL:

psp:\\<target IP address>\NI_SystemState\ControllerStatus\
FaultList

The data type returned by the URL above is identical to that of the fault list output
terminal of this VI.

You also can determine whether a fault is present on a remote target from a host
computer by using the DataSocket Read VI to subscribe to the following URL:

psp:\\<target IP address>\NI_SystemState\ControllerStatus\
FaultPresent

2646 ni.com
 Functions

The data type returned by the URL above is Boolean.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Scan Engine.lvproj

Set Fault

Creates a fault. When the major fault input is TRUE, this VI triggers fault mode. Use the
code element of the error in (user fault) input cluster to specify the fault code.

Inputs/Outputs
• major fault (F) —

major fault specifies whether the fault is major (TRUE) or minor (FALSE).

• error in (user fault) —

error in (user fault) specifies the fault code.

If you do not specify a fault code, the fault code defaults to −66480. This VI triggers a fault based
on the presence of a non-zero error code, regardless of the value of status. You may optionally
provide additional information about the fault in source.

• error adding fault —

error adding fault contains error information related to the creation of the fault. Fault creation
can fail if the NI Scan Engine is not installed on the target or if the target has already reached the
maximum number of active faults (100). Right-click the error out front panel indicator and select
Explain Error from the shortcut menu for more information about the error.

• error out —

error out returns error in (user fault).

© National Instruments 2647

 Functions

This VI does not allocate memory, so you can use this VI in a time-critical section of an
application without significantly affecting determinism.

This VI must run on a target with the NI Scan Engine installed.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Scan Engine.lvproj

Clear Fault

Clears NI Scan Engine faults. If the fault you specify using the fault code input is active,
this VI clears the fault. If the fault is not active, this VI takes no action and generates no
error.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• fault code —

fault code is the code associated with the fault. The VI ignores this input if clear all? is TRUE.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

2648 ni.com
 Functions

This VI does not allocate memory, so you can use this VI in a time-critical section of an
application without significantly affecting determinism.

This VI applies only to targets with the NI Scan Engine installed. You must either run
this VI on a target with the NI Scan Engine installed or use the target address input to
point to a target with the NI Scan Engine installed.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Scan Engine.lvproj

Clear All Faults

Clears all active faults on the target.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

This VI does not allocate memory, so you can use this VI in a time-critical section of an
application without significantly affecting determinism.

This VI applies only to targets with the NI Scan Engine installed. You must either run

© National Instruments 2649

 Functions

this VI on a target with the NI Scan Engine installed or use the target address input to
point to a target with the NI Scan Engine installed.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Scan Engine\Scan Engine.lvproj

Fault Configuration

Use the Fault Configuration VIs to view and configure the level and triggering behavior
of system faults.

Palette Object Description

Set Fault
Applies a custom fault configuration for a configurable fault.
Configuration

Clear Fault Clears the custom fault configuration for a configurable fault and applies the
Configuration default configuration.

Get All Fault

Returns a list of custom fault configurations.
Configurations

Set Fault Configuration

Applies a custom fault configuration for a configurable fault.

If the fault code you specify does not correspond to a configurable fault, this VI returns
an error.

2650 ni.com
 Functions

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• fault configuration —

fault configuration specifies the custom fault configuration to apply.

• code —

code is the fault code of the configurable fault.

• level or level before threshold —

level or level before threshold specifies the level of the specified fault before the
occurrence threshold is met.

Ignore—Each occurrence adds to the occurrence counter used to determine whether the
0
occurrence threshold is met but does not trigger the fault.
1 Minor—Each occurrence triggers the fault as a Minor fault.
2 Major—Each occurrence triggers the fault as a Major fault.

• occurrence threshold —

occurrence threshold specifies the number of times the selected fault can occur before the
level of the fault changes.

• time window in seconds —

time window specifies a time limit for the occurrence threshold. When the time window
expires, LabVIEW resets the internal occurrence counter for the specified fault and restarts
the time window. The default is 0, which specifies not to use the time window and not to
reset the occurrence counter until the NI Scan Engine restarts.

• level after threshold —

© National Instruments 2651

 Functions

level after threshold specifies the level of the specified fault after the occurrence threshold
is met.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

error out contains error information. This output provides standard error out functionality.

Clear Fault Configuration

Clears the custom fault configuration for a configurable fault and applies the default
configuration.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• code to clear —

code to clear is the error code that corresponds to the configurable fault.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• error out —

2652 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Get All Fault Configurations

Returns a list of custom fault configurations.

Inputs/Outputs
• target address (localhost) —

target address specifies the IP address or DNS name of the target.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• configured faults —

configured faults returns information about custom fault configurations on the target.

If none of the configurable faults are currently set to use custom configurations, this output
returns an empty array.

• code —

• level or level before threshold —

• occurrence threshold —

• time window in seconds —

• level after threshold —

• error out —

© National Instruments 2653

 Functions

error out contains error information. This output provides standard error out functionality.

Instrument I/O
Use the Instrument I/O VIs and functions to interface with GPIB, serial, modular, PXI,
and other types of instruments. Use the NI Instrument Driver Finder to search for and
install instrument drivers. If an instrument driver is not available in the NI Instrument
Driver Finder, you can use the Create New Instrument Driver Project wizard to create a
new instrument driver.

If driver VIs you expected to find on this palette are missing, you must install support
for the driver in the current version of LabVIEW.

Note If you installed an instrument driver with a previous version of

LabVIEW, you must reinstall that instrument driver with the current version of
LabVIEW.

Before you begin using the Instrument I/O VIs and functions, make sure you choose the
appropriate method of instrument control.

Palette
Description
Object

Use Instrument Drivers VIs to configure, control, and retrieve data from GPIB, serial,
modular, PXI, and other types of instruments. Use the NI Instrument Driver Finder to
Instrument
search for and install instrument drivers. If an instrument driver is not available, you
Drivers
can use the Create New Instrument Driver Project wizard to create a new instrument
driver.

VISA Use the VISA VIs and functions to program instruments using VISA.

2654 ni.com
 Functions

Palette
Description
Object

GPIB Use the GPIB functions to communicate with GPIB (IEEE-488) devices.

Use the Serial VIs and functions to access the VISA VIs and functions that communicate
Serial with devices connected to a serial port. Additional functions are also available on the
VISA palette.

Instrument Drivers
Use Instrument Drivers VIs to configure, control, and retrieve data from GPIB, serial,
modular, PXI, and other types of instruments. Use the NI Instrument Driver Finder to
search for and install instrument drivers. If an instrument driver is not available, you
can use the Create New Instrument Driver Project wizard to create a new instrument
driver.

The VIs and controls that appear on this palette change depending on the instrument
drivers you install. You can add new VIs and controls to this palette. Before you begin
using the Instrument Driver VIs, make sure you choose the appropriate method of
instrument control.

VISA
Use the VISA VIs and functions to program instruments using VISA.

The VIs and functions on this palette can return VISA error codes.

© National Instruments 2655

 Functions

Palette
Description
Object
VISA
Writes the data from write buffer to the device or interface specified by VISA resource
Write
name.
Function
VISA
Reads the specified number of bytes from the device or interface specified by VISA
Read
resource name and returns the data in read buffer.
Function

VISA
Use the VISA Advanced VIs and functions to accomplish advanced VISA tasks.
Advanced

VISA
Clear Clears the input and output buffers of the device.
Function
VISA
Reads a service request status byte byte from the message-based device specified by
Read STB
VISA resource name.
Function
VISA Asserts a software or hardware trigger, depending on the interface type. For software
Assert triggers, Default (0) is the only valid protocol. For VXI hardware triggers, Default (0) is
Trigger equivalent to Sync (5). For PXI triggers, PXI: Reserve (6) and PXI: Unreserve (7) are the
Function only valid protocols.

VISA Write Function

Writes the data from write buffer to the device or interface specified by VISA resource
name.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

2656 ni.com
 Functions

• write buffer —

write buffer contains the data to be written to the device.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• return count —

return count contains the actual number of bytes written.

• error out —

error out contains error information. This output provides standard error out functionality.

Whether the data is transferred synchronously or asynchronously is platform-

dependent. Right-click the node and select Synchronous I/O Mode»Synchronous from
the shortcut menu to write data synchronously.

When you transfer data from or to a hardware driver synchronously, the calling thread
is locked for the duration of the data transfer. Depending on the speed of the transfer,
this can hinder other processes that require the calling thread. However, if an
application requires that the data transfer as quickly as possible, performing the
operation synchronously dedicates the calling thread exclusively to this operation.

Note In most applications, synchronous calls are slightly faster when you
are communicating with four or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with
five or more instruments. The LabVIEW default is asynchronous I/O.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2657

 Functions

• labview\examples\Instrument IO\Serial\Serial.lvproj
• labview\examples\Instrument IO\GPIB\GPIB with VISA
functions.vi

VISA Read Function

Reads the specified number of bytes from the device or interface specified by VISA
resource name and returns the data in read buffer.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• byte count —

byte count is the number of bytes to be read.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• read buffer —

read buffer contains the data read from the device.

• return count —

return count contains the number of bytes actually read.

• error out —

2658 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

This function might return less than the number of bytes requested if the function
reaches the end of the buffer, reaches a termination character, or if a timeout occurs.
The output error cluster indicates if a timeout has occurred.

Whether the data is read synchronously or asynchronously is platform-dependent.

Right-click the node and select Synchronous I/O Mode»Synchronous from the
shortcut menu to read data synchronously.

When you transfer data from or to a hardware driver synchronously, the calling thread
is locked for the duration of the data transfer. Depending on the speed of the transfer,
this can hinder other processes that require the calling thread. However, if an
application requires that the data transfer as quickly as possible, performing the
operation synchronously dedicates the calling thread exclusively to this operation.

Note In most applications, synchronous calls are slightly faster when you
are communicating with 4 or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with 5
or more instruments. The LabVIEW default is asynchronous I/O.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Continuous Serial

Write and Read.vi
• labview\examples\Instrument IO\VISA\USB\USB RAW - Bulk.vi
• labview\examples\Instrument IO\GPIB\GPIB with VISA
functions.vi

VISA Advanced

Use the VISA Advanced VIs and functions to accomplish advanced VISA tasks.

© National Instruments 2659

 Functions

The VIs and functions on this palette can return VISA error codes.

Palette
Description
Object
VISA Open Opens a session to the device specified by VISA resource name and returns a session
Function identifier that can be used to call any other operations of that device.
VISA Close
Closes a device session or event object specified by VISA resource name.
Function
VISA Find
Resource Queries the system to locate the devices associated with a specified interface.
Function

VISA Set
Sets the Timeout value, in milliseconds, for the VISA session.
Timeout

VISA
Gets (reads) and/or sets (writes) properties of a reference. The node operates in the
Property
same way as a standard Property Node.
Node

Bus/
Use the Bus/Interface Specific functions to program instruments that are interface
Interface
specific.
Specific

VISA Write
Takes data from the file specified by filename and writes it to the device
From File
synchronously.
Function
VISA Read
Reads byte count synchronously and stores the transferred data in the file specified
To File
by filename.
Function

Event
Use the Event Handling VIs and functions to use VISA events with your instruments.
Handling

VISA Lock Asynchronously attempts to establish access to the device or interface specified by
Async VISA resource name. Use this function to obtain an exclusive lock that guarantees

2660 ni.com
 Functions

Palette
Description
Object

sole access to a device or resource.

VISA
Unlock Relinquishes the lock previously obtained using the VISA Lock Async function.
Function

Register
Use the Register Access functions to program in an address space at a high level.
Access

VISA Open Function

Opens a session to the device specified by VISA resource name and returns a session
identifier that can be used to call any other operations of that device.

Inputs/Outputs
• VISA Open timeout (0) —

VISA Open timeout specifies the maximum time period, in milliseconds, that VISA Open waits
before returning an error. It does not set the I/O timeout.

To specify the timeout used for future operations on the VISA session, use VISA Set Timeout.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• duplicate session (F) —

If duplicate session is TRUE and there is currently a session opened to the resource, another

© National Instruments 2661

 Functions

session is opened to the resource. If duplicate session is set to FALSE and a session is opened to
the resource, the open session is used.

A VISA session is a unique logical identifier used by VISA to communicate with a resource. The
VISA session is maintained by the VISA resource name control and is not seen by the user.

• access mode —

access mode specifies how to access the device.

This input accepts the following values.

VISA Defaults (default)—Open session without using an exclusive lock or loading configuration
0
information.
Exclusive Lock—Acquire an exclusive lock immediately upon opening a session. If a lock
1
cannot be acquired, the session is closed and an error is returned.
Load Configured Settings—Configure attributes to values specified by an external
configuration utility, such as the following utilities:
4 • (Windows) Measurement & Automation Explorer
• (Mac OS X) NI-VISA Configuration
• (Linux) visaconf

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is the resource to which a VISA session is opened and its class. The class
matches that of the VISA resource name input.

Refer to VISA resource name control for more information.

• error out —

error out contains error information. This output provides standard error out functionality.

If you open a significant number of VISA sessions without closing them, you decrease
the available memory resources. Close the session with the VISA Close function.

2662 ni.com
 Functions

Note This function recognizes all resource strings returned by VISA Find
Resource. However, VISA Find Resource does not necessarily return all strings
that you pass to this function.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\GPIB\GPIB with VISA

functions.vi

VISA Close Function

Closes a device session or event object specified by VISA resource name.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

error out contains error information. This output provides standard error out functionality.

Error I/O operates uniquely in this function. The function closes the device session
regardless of whether an error occurred in a preceding operation. For each VISA

© National Instruments 2663

 Functions

session that you open, you should close the session when you are finished with it. This
function accepts all available classes.

You also can use the Open VISA Session Monitor VI in the labview\vi.lib\
Utility\visa.llb to close all open VISA sessions. Alternatively, you could save
work, exit, and re-enter LabVIEW. Exiting LabVIEW closes all open VISA sessions. You
also can select the Automatically close VISA sessions option on the Environment
page of the Options dialog box.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Continuous Serial

Write and Read.vi
• labview\examples\Instrument IO\VISA\PXI\PXI - Route
Trigger.vi
• labview\examples\Instrument IO\GPIB\GPIB with VISA
functions.vi
• labview\examples\Instrument IO\VISA\USB\USB RAW -
Interrupt.vi

VISA Find Resource Function

Queries the system to locate the devices associated with a specified interface.

Inputs/Outputs
• expression ("?*") —

expression matches the value specified with the devices available for a particular interface.

The description string specified sets the criteria to search an interface—GPIB, GPIB-VXI, VXI, All
VXI, Serial, or All—for existing devices. The following table includes valid special characters and

2664 ni.com
 Functions

operators.

Special
Characters
Meaning
and
Operators
? Matches any one character.
Makes the character that follows it an ordinary character instead of special
\ character. For example, when a question mark follows a backslash (\?), it matches
the ? character instead of any one character.
Matches any one character from the enclosed list. You can use a hyphen to match a
[list]
range of characters.
Matches any character not in the enclosed list. You can use a hyphen to match a
[^list]
range of characters.
* Matches 0 or more occurrences of the preceding character or expression.
+ Matches 1 or more occurrences of the preceding character or expression.
Matches either the preceding or following expression. The or operator | matches the
Exp|exp entire expression that precedes or follows it and not just the character that precedes
or follows it. For example, VXI|GPIB means (VXI)|(GPIB), not VX(I|G)PIB.
(exp) Grouping characters or expressions.

The search criteria specified in the expression parameter has two parts, a regular expression
over a resource string and an optional logical expression over attribute values. The regular
expression is matched against the resource strings of resources known to the VISA Resource
Manager. If the resource string matches the regular expression, the attribute values of the
resource are matched against the expression over attribute values. If the match is successful, the
resource has met the search criteria and is added to the list of resources found. The following
table includes valid regular expressions.

Regular Expression Sample Matches

Matches GPIB0::2::INSTR, GPIB1::1::1::INSTR, and
GPIB?*INSTR
GPIB-VXI1::8::INSTR.
Matches GPIB0::2::INSTR and GPIB1::1::1::INSTR
GPIB[0-9]*::?*INSTR
but not GPIB-VXI1::8::INSTR.
Matches GPIB1::1::1::INSTR but not
GPIB[^0]::?*INSTR
GPIB0::2::INSTR or GPIB12::8::INSTR.
Matches VXI0::1::INSTR but not GPIB-
VXI?*INSTR
VXI0::1::INSTR.
Matches GPIB-VXI0::1::INSTR but not
GPIB-VXI?*INSTR
VXI0::1::INSTR.

© National Instruments 2665

 Functions

Regular Expression Sample Matches

?*VXI[0-9]*::?*INSTR Matches VXI0::1::INSTR and GPIB-VXI0::1::INSTR.
ASRL[0-9]*::?*INSTR Matches ASRL1::INSTR but not VXI0::5::INSTR.
Matches ASRL1::INSTR and ASRL11::INSTR but not
ASRL1+::INSTR
ASRL2::INSTR.
Matches GPIB1::5::INSTR and VXI0::3::INSTR but not
(GPIB|VXI)?*INSTR
ASRL2::INSTR.
(GPIB0|VXI0)::1::INSTR Matches GPIB0::1::INSTR and VXI0::1::INSTR.
?*INSTR Matches all INSTR (device) resources.
?*VXI[0-9]*::?*MEMACC Matches VXI0::MEMACC and GPIB-VXI1::MEMACC.
Matches VXI0::1::INSTR, VXI0::2::INSTR, and
VXI0::?*
VXI0::MEMACC.
?* (default) Matches all resources.
Matches all resources on the specified remote system. You can
set the hostname as either an IP address (dot-notation) or a
visa://hostname/?*
network machine name. This remote system does not need to
be a configured remote system.
Matches all resources on the local machine. Does not query
/?*
configured remote systems.
Matches all ASRL resources on the local machine and returns
visa:/ASRL?*INSTR
them in URL format, such as visa:/ASRL1::INSTR.

By using the optional attribute expression, you can construct flexible and powerful expressions
with the use of logical ANDs (&&), ORs(||), and NOTs (!). You can use equal (==) and unequal (!=)
comparators to compare attributes of any data type, and other inequality comparators (>, <, >=,
<=) to compare attributes of numeric data type. Use only global attributes in the attribute
expression. Local attributes are not allowed in the logical expression part of the expr parameter.
The following table includes valid expression parameters.

Expr Parameter Meaning

Find all GPIB
devices that have
GPIB[0-9]*::?*::?*::INSTR{VI_ATTR_GPIB_SECONDARY_ADDR
secondary
> 0 && VI_ATTR_GPIB_SECONDARY_ADDR < 10}
addresses from 1
to 9.
Find all serial ports
ASRL?*INSTR{VI_ATTR_ASRL_BAUD == 9600} configured at 9600
baud.
?*VXI?INSTR{VI_ATTR_MANF_ID == 0xFF6 && Find all VXI
!(VI_ATTR_VXI_LA ==0 || VI_ATTR_SLOT <= 0)} instrument

2666 ni.com
 Functions

Expr Parameter Meaning

resources having
manufacturer ID
FF6 and which are
not logical address
0, slot 0, or external
controllers.

• search mode (0) —

search mode determines how the function returns found interfaces in the find list output, either
by canonical names or aliases. The default is 0.

This input accepts the following values.

Canonical Names Only—Search all configured buses. Returns only the resources found that
0 match the expression string. The format of each returned string is the VISA canonical spec-
defined resource format.
Aliases Only—Search all configured buses. Returns only the resources found that match the
expression string. For each resource, if there is a user-defined alias for that resource, that alias
2
is returned. For the other resources, the returned string is in the VISA canonical spec-defined
resource format.
Include Matching Aliases—Do not search any buses. Returns only resources with user-defined
3
aliases. The only valid expression string is "?*". The format of each returned string is an alias.
Include All Aliases—Search all configured buses. Returns all found resources that match the
expression string and all user-defined aliases even if they do not match the expression string.
4
For each resource, the function returns a user-defined alias if there is one for that resource. For
the other resources, the returned string is in the VISA canonical spec-defined resource format.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• find list —

find list is an array of strings, each string specifying one interface found by the function.

• return count —

return count specifies the number of matches found. The number of matches found is the
number of strings in the find list array.

© National Instruments 2667

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

LabVIEW lists resources in an I/O control according to the chosen I/O control class type
and the Filter VISA Names dialog box, so you might not need to call this function.

All resource strings returned by this function are recognized by VISA Open. However,
this function does not necessarily return all strings that you pass to the VISA Open
function. This is especially true for network and TCP/IP resources. If a resource does
not appear in the list, you can explicitly add the resource in the NI-VISA configuration
utility, such as (Windows) Measurement & Automation Explorer, (Linux) visaconf, or
(Mac OS X) NI-VISA Configuration. The configuration utility also has options that
expand or limit the set of resources that this VI returns.

VISA Set Timeout

Sets the Timeout value, in milliseconds, for the VISA session.

VISA Set Timeout is a Property Node with a VISA class of Instr.

Inputs/Outputs
• reference —

• error in (no error) —

• General Settings:Timeout Value —

• reference out —

• error out —

2668 ni.com
 Functions

VISA Property Node

Gets (reads) and/or sets (writes) properties of a reference. The node operates in the
same way as a standard Property Node.

Inputs/Outputs
• reference —
reference is the refnum associated with the object for which you want to set or get properties.

If the Property Node class is Application or VI, you do not have to wire a refnum to this input. For
the Application class, the default is the current application instance. For the VI class, the default
is the VI containing the Property Node.

You also can wire a LabVIEW class to the reference input to access the private data of the
LabVIEW class.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.
• property 2 — property 2..n are examples of properties you want to set (write).
• reference out —
reference out returns reference unchanged.
• error out —
error out contains error information. This output provides standard error out functionality.
• property 1 — property 1..n are examples of properties you want to get (read).
• Property —

Bus/Interface Specific

Use the Bus/Interface Specific functions to program instruments that are interface
specific.

The functions on this palette can return VISA error codes.

© National Instruments 2669

 Functions

Palette Object Description

Use the Serial VIs and functions to access the VISA VIs and functions that
Serial communicate with devices connected to a serial port. Additional functions are
also available on the VISA palette.

VISA USB Use the VISA USB VI and functions to control USB devices.

VISA Set I/O

Sets the size of the I/O buffer. Run the VISA Configure Serial Port VI first if you are
Buffer Size
setting the size of a serial port buffer.
Function
VISA Flush I/O
Flushes the I/O buffer specified by mask.
Buffer Function
VISA GPIB
Command Writes GPIB command bytes on the bus.
Function
VISA GPIB
Controls the state of the GPIB ATN interface line and, optionally, the active
Control ATN
controller state of the local interface.
Function
VISA GPIB Pass
Tells the GPIB device at the specified address to become controller-in-charge
Control
(CIC).
Function
VISA GPIB Send
Pulses the interface clear line (IFC) for at least 100 microseconds.
IFC Function
VISA GPIB
Control REN Asserts or deasserts the GPIB REN interface line according to the specified mode.
Function
VISA VXI Cmd
Sends the device a miscellaneous command or query and/or retrieves the
or Query
response to a previous query.
Function
VISA Assert
Interrupt Asserts the specified device interrupt or signal.
Signal Function

2670 ni.com
 Functions

Palette Object Description

VISA Assert
Utility Signal Asserts or deasserts the specified utility bus signal.
Function
VISA Map
Trigger Maps the specified trigger source line to the specified trigger destination line.
Function
VISA Unmap
Unmaps a previous map from the specified trigger source line to the specified
Trigger
trigger destination line. This function unmaps one trigger mapping per call.
Function

Serial
Use the Serial VIs and functions to access the VISA VIs and functions that communicate
with devices connected to a serial port. Additional functions are also available on the
VISA palette.

The VIs and functions on this palette can return serial error codes.

Palette
Description
Object

VISA Initializes the serial port specified by VISA resource name to the specified settings.
Configure Wire data to the VISA resource name input to determine the polymorphic instance to
Serial Port use or manually select the instance.

VISA Write Writes the data from write buffer to the device or interface specified by VISA
Function resource name.
VISA Read Reads the specified number of bytes from the device or interface specified by VISA
Function resource name and returns the data in read buffer.
VISA Close
Closes a device session or event object specified by VISA resource name.
Function

© National Instruments 2671

 Functions

Palette
Description
Object
VISA Bytes
at Serial Returns the number of bytes in the input buffer of the specified serial port.
Port

VISA Serial Sends a break on the specified output port. Wire data to the VISA resource name
Break input to determine the polymorphic instance to use or manually select the instance.

VISA Set I/O

Sets the size of the I/O buffer. Run the VISA Configure Serial Port VI first if you are
Buffer Size
setting the size of a serial port buffer.
Function
VISA Flush
I/O Buffer Flushes the I/O buffer specified by mask.
Function

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Serial.lvproj

VISA Configure Serial Port

Initializes the serial port specified by VISA resource name to the specified settings.
Wire data to the VISA resource name input to determine the polymorphic instance to
use or manually select the instance.

• VISA Configure Serial Port (Instr) VI

• VISA Configure Serial Port (Serial Instr) VI

2672 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Serial.lvproj

VISA Configure Serial Port (Instr) VI

Initializes the serial port specified by VISA resource name to the specified settings.
Wire data to the VISA resource name input to determine the polymorphic instance to
use or manually select the instance.

Inputs/Outputs
• Enable Termination Char (T) —

Enable Termination Char prepares the serial device to recognize termination char.

If TRUE (default), the VI_ATTR_ASRL_END_IN attribute is set to recognize the termination

character. If FALSE, the VI_ATTR_ASRL_END_IN attribute is set to 0 (None) and the serial device
does not recognize the termination char.

• termination char (0xA = '\n' = LF) —

termination char calls for termination of the read operation. The read operation terminates
when the termination char is read from the serial device.

0xA is the hex equivalent of a linefeed character (\n). Change the termination char to 0xD for
message strings that terminate with a carriage return (\r).

• timeout (10sec) —

© National Instruments 2673

 Functions

timeout specifies the time, in milliseconds, for the write and read operations.

The default is 10000.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• baud rate (9600) —

baud rate is the rate of transmission.

The default is 9600.

• data bits (8) —

data bits is the number of bits in the incoming data.

The value of data bits is between five and eight. The default value is 8.

• parity (0:none) —

parity specifies the parity used for every frame to be transmitted or received.

This input accepts the following values.

no parity
0
(default)
1 odd parity
2 even parity
3 mark parity
4 space parity

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• stop bits (10: 1 bit) —

stop bits specifies the number of stop bits used to indicate the end of a frame.

2674 ni.com
 Functions

This input accepts the following values.

10 1 stop bit
15 1.5 stop bits
20 2 stop bits

• flow control (0:none) —

flow control sets the type of control used by the transfer mechanism.

This input accepts the following values.

None (default)—The transfer mechanism does not use flow control. Buffers on both sides of the
0
connection are assumed to be large enough to hold all data transferred.
XON/XOFF—The transfer mechanism uses the XON and XOFF characters to perform flow
control. The transfer mechanism controls input flow by sending XOFF when the receive buffer
1
is nearly full, and it controls the output flow by suspending transmission when XOFF is
received.
RTS/CTS—The transfer mechanism uses the RTS output signal and the CTS input signal to
perform flow control. The transfer mechanism controls input flow by unasserting the RTS
2
signal when the receive buffer is nearly full, and it controls output flow by suspending the
transmission when the CTS signal is unasserted.
XON/XOFF and RTS/CTS—The transfer mechanism uses the XON and XOFF characters and the
RTS output signal and CTS input signal to perform flow control. The transfer mechanism
3 controls input flow by sending XOFF and unasserting the RTS signal when the receive buffer is
nearly full, and it controls the output flow by suspending transmission when XOFF is received
and the CTS is unasserted.
DTR/DSR—The transfer mechanism uses the DTR output signal and the DSR input signal to
perform flow control. The transfer mechanism controls input flow by unasserting the DTR
4
signal when the receive buffer is nearly full, and it controls output flow by suspending the
transmission when the DSR signal is unasserted.
XON/XOFF and DTR/DSR—The transfer mechanism uses the XON and XOFF characters and the
DTR output signal and DSR input signal to perform flow control. The transfer mechanism
5 controls input flow by sending XOFF and unasserting the DTR signal when the receive buffer is
nearly full, and it controls the output flow by suspending transmission when XOFF is received
and the DSR signal is unasserted.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

© National Instruments 2675

 Functions

error out contains error information. This output provides standard error out functionality.

VISA Configure Serial Port (Serial Instr) VI

Initializes the serial port specified by VISA resource name to the specified settings.
Wire data to the VISA resource name input to determine the polymorphic instance to
use or manually select the instance.

Inputs/Outputs
• Enable Termination Char (T) —

Enable Termination Char prepares the serial device to recognize termination char.

If TRUE (default), the VI_ATTR_ASRL_END_IN attribute is set to recognize the termination

character. If FALSE, the VI_ATTR_ASRL_END_IN attribute is set to 0 (None) and the serial device
does not recognize the termination char.

• termination char (0xA = '\n' = LF) —

termination char calls for termination of the read operation. The read operation terminates
when the termination char is read from the serial device.

0xA is the hex equivalent of a linefeed character (\n). Change the termination char to 0xD for
message strings that terminate with a carriage return (\r).

• timeout (10sec) —

timeout specifies the time, in milliseconds, for the write and read operations.

2676 ni.com
 Functions

The default is 10000.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• baud rate (9600) —

baud rate is the rate of transmission.

The default is 9600.

• data bits (8) —

data bits is the number of bits in the incoming data.

The value of data bits is between five and eight. The default value is 8.

• parity (0:none) —

parity specifies the parity used for every frame to be transmitted or received.

This input accepts the following values.

no parity
0
(default)
1 odd parity
2 even parity
3 mark parity
4 space parity

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• stop bits (10: 1 bit) —

stop bits specifies the number of stop bits used to indicate the end of a frame.

This input accepts the following values.

© National Instruments 2677

 Functions

10 1 stop bit
15 1.5 stop bits
20 2 stop bits

• flow control (0:none) —

flow control sets the type of control used by the transfer mechanism.

This input accepts the following values.

None (default)—The transfer mechanism does not use flow control. Buffers on both sides of the
0
connection are assumed to be large enough to hold all data transferred.
XON/XOFF—The transfer mechanism uses the XON and XOFF characters to perform flow
control. The transfer mechanism controls input flow by sending XOFF when the receive buffer
1
is nearly full, and it controls the output flow by suspending transmission when XOFF is
received.
RTS/CTS—The transfer mechanism uses the RTS output signal and the CTS input signal to
perform flow control. The transfer mechanism controls input flow by unasserting the RTS
2
signal when the receive buffer is nearly full, and it controls output flow by suspending the
transmission when the CTS signal is unasserted.
XON/XOFF and RTS/CTS—The transfer mechanism uses the XON and XOFF characters and the
RTS output signal and CTS input signal to perform flow control. The transfer mechanism
3 controls input flow by sending XOFF and unasserting the RTS signal when the receive buffer is
nearly full, and it controls the output flow by suspending transmission when XOFF is received
and the CTS is unasserted.
DTR/DSR—The transfer mechanism uses the DTR output signal and the DSR input signal to
perform flow control. The transfer mechanism controls input flow by unasserting the DTR
4
signal when the receive buffer is nearly full, and it controls output flow by suspending the
transmission when the DSR signal is unasserted.
XON/XOFF and DTR/DSR—The transfer mechanism uses the XON and XOFF characters and the
DTR output signal and DSR input signal to perform flow control. The transfer mechanism
5 controls input flow by sending XOFF and unasserting the DTR signal when the receive buffer is
nearly full, and it controls the output flow by suspending transmission when XOFF is received
and the DSR signal is unasserted.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

2678 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

VISA Write Function

Writes the data from write buffer to the device or interface specified by VISA resource
name.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• write buffer —

write buffer contains the data to be written to the device.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• return count —

return count contains the actual number of bytes written.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2679

 Functions

Whether the data is transferred synchronously or asynchronously is platform-

dependent. Right-click the node and select Synchronous I/O Mode»Synchronous from
the shortcut menu to write data synchronously.

When you transfer data from or to a hardware driver synchronously, the calling thread
is locked for the duration of the data transfer. Depending on the speed of the transfer,
this can hinder other processes that require the calling thread. However, if an
application requires that the data transfer as quickly as possible, performing the
operation synchronously dedicates the calling thread exclusively to this operation.

Note In most applications, synchronous calls are slightly faster when you
are communicating with four or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with
five or more instruments. The LabVIEW default is asynchronous I/O.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Serial.lvproj
• labview\examples\Instrument IO\GPIB\GPIB with VISA
functions.vi

VISA Read Function

Reads the specified number of bytes from the device or interface specified by VISA
resource name and returns the data in read buffer.

Inputs/Outputs
• VISA resource name —

2680 ni.com
 Functions

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• byte count —

byte count is the number of bytes to be read.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• read buffer —

read buffer contains the data read from the device.

• return count —

return count contains the number of bytes actually read.

• error out —

error out contains error information. This output provides standard error out functionality.

This function might return less than the number of bytes requested if the function
reaches the end of the buffer, reaches a termination character, or if a timeout occurs.
The output error cluster indicates if a timeout has occurred.

Whether the data is read synchronously or asynchronously is platform-dependent.

Right-click the node and select Synchronous I/O Mode»Synchronous from the
shortcut menu to read data synchronously.

When you transfer data from or to a hardware driver synchronously, the calling thread
is locked for the duration of the data transfer. Depending on the speed of the transfer,
this can hinder other processes that require the calling thread. However, if an
application requires that the data transfer as quickly as possible, performing the
operation synchronously dedicates the calling thread exclusively to this operation.

© National Instruments 2681

 Functions

Note In most applications, synchronous calls are slightly faster when you
are communicating with 4 or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with 5
or more instruments. The LabVIEW default is asynchronous I/O.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Continuous Serial

Write and Read.vi
• labview\examples\Instrument IO\VISA\USB\USB RAW - Bulk.vi
• labview\examples\Instrument IO\GPIB\GPIB with VISA
functions.vi

VISA Close Function

Closes a device session or event object specified by VISA resource name.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• error out —

2682 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

Error I/O operates uniquely in this function. The function closes the device session
regardless of whether an error occurred in a preceding operation. For each VISA
session that you open, you should close the session when you are finished with it. This
function accepts all available classes.

You also can use the Open VISA Session Monitor VI in the labview\vi.lib\
Utility\visa.llb to close all open VISA sessions. Alternatively, you could save
work, exit, and re-enter LabVIEW. Exiting LabVIEW closes all open VISA sessions. You
also can select the Automatically close VISA sessions option on the Environment
page of the Options dialog box.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Continuous Serial

Write and Read.vi
• labview\examples\Instrument IO\VISA\PXI\PXI - Route
Trigger.vi
• labview\examples\Instrument IO\GPIB\GPIB with VISA
functions.vi
• labview\examples\Instrument IO\VISA\USB\USB RAW -
Interrupt.vi

VISA Bytes at Serial Port

Returns the number of bytes in the input buffer of the specified serial port.

The Number of Bytes at Serial Port property specifies the number of bytes currently
available at the serial port used by this session.

Visa Bytes at Serial Port is a Property Node with a VISA class of Instr.

© National Instruments 2683

 Functions

Inputs/Outputs
• reference —

• error in (no error) —

• reference out —

• error out —

• Serial Settings:Number of Bytes at Serial Port —

VISA Serial Break

Sends a break on the specified output port. Wire data to the VISA resource name input
to determine the polymorphic instance to use or manually select the instance.

• VISA Serial Break (Instr) VI

• VISA Serial Break (Serial Instr) VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Set Serial Break

Event.vi

2684 ni.com
 Functions

VISA Serial Break (Instr) VI

Sends a break on the specified output port. Wire data to the VISA resource name input
to determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• Duration (-1 : use default) —

Duration specifies the length of the break in milliseconds.

While the VI runs, this value temporarily overrides the current setting of the VISA Serial
Settings:Break Length property. Afterwards, the VI returns the current setting to its original
value.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2685

 Functions

• labview\examples\Instrument IO\Serial\Set Serial Break

Event.vi

VISA Serial Break (Serial Instr) VI

Sends a break on the specified output port. Wire data to the VISA resource name input
to determine the polymorphic instance to use or manually select the instance.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• Duration (-1 : use default) —

Duration specifies the length of the break in milliseconds.

While the VI runs, this value temporarily overrides the current setting of the VISA Serial
Settings:Break Length property. Afterwards, the VI returns the current setting to its original
value.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

2686 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Set Serial Break

Event.vi

VISA Set I/O Buffer Size Function

Sets the size of the I/O buffer. Run the VISA Configure Serial Port VI first if you are
setting the size of a serial port buffer.

Note Not all serial drivers support user-defined buffer sizes so some
implementations of VISA might not be able to perform this operation. If an
application requires a specific buffer size for performance reasons and the
VISA implementation cannot guarantee that size, use some form of
handshaking to prevent overflow conditions.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mask (16) —

mask designates which buffer size to set.

16 I/O Receive Buffer

32 I/O Transmit Buffer
48 I/O Receive and Transmit Buffer

© National Instruments 2687

 Functions

• size (4096) —

size designates the size of the I/O buffer in bytes. Set size slightly higher than the amount of data
you expect to transmit or receive. If you call this function without specifying a buffer size, this
function sets the buffer size to 4096 bytes. If you do not call this function, the buffer size depends
on both VISA and the operating system configuration.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Continuous Serial

Write and Read.vi

VISA Flush I/O Buffer Function

Flushes the I/O buffer specified by mask.

Inputs/Outputs
• VISA resource name —

2688 ni.com
 Functions

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mask (16) —

mask designates the buffer to flush.

Combine the buffer masks by bit to flush more than one buffer simultaneously. Use logical OR,
also known as OR-ing or adding, to combine the values. Use only one mask value for the receive
buffer and only one mask value for the transmit buffer.

This input accepts the following values.

Mask Hex
Description
Values Codes
16 0x10 Flushes and discards contents of the receive buffer (same as 64).
Flushes and discards contents of the transmit buffer by writing all the
32 0x20
buffered data to the device.
Flushes and discards contents of the receive buffer (does not perform any I/O
64 0x40
to the device).
Flushes and discards contents of the transmit buffer (does not perform any
128 0x80
I/O to the device).

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA USB
Use the VISA USB VI and functions to control USB devices.

© National Instruments 2689

 Functions

The VI and functions on this palette can return VISA error codes.

Palette Object Description

VISA USB Control In Function Performs a USB control pipe transfer from a USB device.
VISA USB Control Out
Performs a USB control pipe transfer to the device.
Function

Retrieves the interrupt data that is stored in a VISA USB interrupt

VISA Get USB Interrupt Data
event.

VISA USB Control In Function

Performs a USB control pipe transfer from a USB device.

Inputs/Outputs
• index (0) —

index passes a parameter to the device. The value you enter here depends on the value you
entered in request.

The index is often used in requests to specify an endpoint or an interface.

• value (0) —

value passes a parameter to the device. The value you enter here depends on the value you
enter in request.

2690 ni.com
 Functions

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• request type —

request type is the numeric representation of the request you want to send to the device.

This parameter is a bitmapped field that identifies the characteristics of the specific request. The
bit specifying the direction must be set to 1 (device-to-host).
• request —

request specifies the particular request. The request you can enter depends on the value you
entered in request type.

• length (0) —

length specifies the length of the data transferred during the second phase of the control
transfer. The direction is device-to-host.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• read buffer —

read buffer contains the data read from the device.

• error out —

error out contains error information. This output provides standard error out functionality.

This function takes the values of the data payload in the setup stage of the control
transfer as parameters. The function reads the optional data buffer read buffer if you
require a data stage for this transfer.

© National Instruments 2691

 Functions

Note This function is only intended for users familiar with the USB protocol.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\VISA\USB\USB RAW -

Control.vi

VISA USB Control Out Function

Performs a USB control pipe transfer to the device.

Inputs/Outputs
• index (0) —

index passes a parameter to the device. The value you enter here depends on the value you
entered in request.

The index is often used in requests to specify an endpoint or an interface.

• value (0) —

value passes a parameter to the device. The value you enter here depends on the value you
enter in request.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• request type —

2692 ni.com
 Functions

request type is the numeric representation of the request you want to send to the device.

This parameter is a bitmapped field that identifies the characteristics of the specific request. The
bit specifying the direction must be set to 0 (host-to-device).
• request —

request specifies the particular request. The request you can enter depends on the value you
entered in request type.

• write buffer (empty) —

write buffer contains the data to be written to the device.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

This function takes the values of the data payload in the setup stage of the control
transfer as parameters. The function sends an optional data buffer write buffer if you
require a data stage for this transfer.

Note This function is only intended for users familiar with the USB protocol.

VISA Get USB Interrupt Data

Retrieves the interrupt data that is stored in a VISA USB interrupt event.

© National Instruments 2693

 Functions

Inputs/Outputs
• VISA USB Intr Event —

VISA USB Intr Event is a unique logical identifier to a VISA USB Interrupt Event.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA USB Intr Event out —

VISA USB Intr Event out is a copy of the VISA USB Intr Event that is passed out of the VISA
functions.

• data buffer —

data buffer is the buffer of USB interrupt data.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Set I/O Buffer Size Function

Sets the size of the I/O buffer. Run the VISA Configure Serial Port VI first if you are
setting the size of a serial port buffer.

Note Not all serial drivers support user-defined buffer sizes so some
implementations of VISA might not be able to perform this operation. If an
application requires a specific buffer size for performance reasons and the
VISA implementation cannot guarantee that size, use some form of
handshaking to prevent overflow conditions.

2694 ni.com
 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mask (16) —

mask designates which buffer size to set.

16 I/O Receive Buffer

32 I/O Transmit Buffer
48 I/O Receive and Transmit Buffer

• size (4096) —

size designates the size of the I/O buffer in bytes. Set size slightly higher than the amount of data
you expect to transmit or receive. If you call this function without specifying a buffer size, this
function sets the buffer size to 4096 bytes. If you do not call this function, the buffer size depends
on both VISA and the operating system configuration.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

© National Instruments 2695

 Functions

• labview\examples\Instrument IO\Serial\Continuous Serial

Write and Read.vi

VISA Flush I/O Buffer Function

Flushes the I/O buffer specified by mask.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mask (16) —

mask designates the buffer to flush.

Combine the buffer masks by bit to flush more than one buffer simultaneously. Use logical OR,
also known as OR-ing or adding, to combine the values. Use only one mask value for the receive
buffer and only one mask value for the transmit buffer.

This input accepts the following values.

Mask Hex
Description
Values Codes
16 0x10 Flushes and discards contents of the receive buffer (same as 64).
Flushes and discards contents of the transmit buffer by writing all the
32 0x20
buffered data to the device.
Flushes and discards contents of the receive buffer (does not perform any I/O
64 0x40
to the device).
Flushes and discards contents of the transmit buffer (does not perform any
128 0x80
I/O to the device).

• error in (no error) —

2696 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA GPIB Command Function

Writes GPIB command bytes on the bus.

Note GPIB Command does not accept VISA sessions of class Instr. The VISA
session must be of class GPIB BoardInterface.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• command —

command The command bytes should be valid IEEE 488-defined Multiline Interface Messages.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

© National Instruments 2697

 Functions

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• return count —

return count is the number of bytes actually transferred.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA GPIB Control ATN Function

Controls the state of the GPIB ATN interface line and, optionally, the active controller
state of the local interface.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mode —

mode specifies the state of the ATN line and optionally the local active controller state.

This input accepts the following values.

Deassert ATN—Deassert ATN line. The GPIB interface corresponding to the VISA session goes to
0
standby.
Assert ATN—Assert ATN line and take control synchronously without corrupting transferred
1
data. If a data handshake is in progress, ATN is not asserted until the handshake is complete.
Deassert ATN with Handshake—Deassert ATN line and enter shadow handshake mode. The
2
local device participates in data handshakes as an Acceptor without actually reading the data.

2698 ni.com
 Functions

The GPIB interface corresponding to the VISA session goes to standby.

Assert ATN Immediately—Assert ATN line and take control asynchronously and immediately,
3 without regard for any data transfer currently in progress. Use this mode only under error
conditions.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Most applications do not require this function. You can use the VISA GPIB Command
function to modify the ATN automatically and the VISA GPIB Pass Control function to
modify the ATN and controller-in-charge (CIC) state automatically.

Note GPIB Command does not accept VISA sessions of class Instr. The VISA
session must be of class GPIB BoardInterface.

VISA GPIB Pass Control Function

Tells the GPIB device at the specified address to become controller-in-charge (CIC).

Inputs/Outputs
• VISA resource name —

© National Instruments 2699

 Functions

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• primary address —

primary address is the primary address of the GPIB device to which you want to pass control.

• secondary address (none) —

secondary address is the secondary address of the targeted GPIB device.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

This function passes CIC status to the device specified by primary address and
secondary address and deasserts the ATN line. This function assumes that the
targeted device has controller capability.

Note VISA GPIB Pass Control does not accept VISA sessions of class Instr. The
VISA session must be of class GPIB BoardInterface.

VISA GPIB Send IFC Function

Pulses the interface clear line (IFC) for at least 100 microseconds.

This function asserts the IFC line and becomes the controller-in-charge (CIC). The local
device must be the system controller.

2700 ni.com
 Functions

Note VISA GPIB Send IFC does not accept VISA sessions of class Instr. The
VISA session must be of class GPIB BoardInterface.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA GPIB Control REN Function

Asserts or deasserts the GPIB REN interface line according to the specified mode.

mode also can specify the remote/local state of the device.

Note VISA GPIB Control REN is valid only if the GPIB interface associated
with the specified session is currently the system controller.

© National Instruments 2701

 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mode —

mode specifies the state of the REN line and optionally the device remote/local state.

This input accepts the following values.

0 Deassert REN—Deassert REN line.

1 Assert REN—Assert REN line.
2 Go To Local; Deassert REN—Send the Go To Local (GTL) command and deassert REN line.
3 Assert REN; Address Device—Assert REN line and address device.
4 Local Lockout (Addressed Devices)—Send LLO to any devices that are addressed to listen.
5 Local Lockout (This Device)—Address this device and send it LLO, putting it in RWLS.
6 Go To Local—Send the Go To Local command (GTL) to this device.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA VXI Cmd or Query Function

Sends the device a miscellaneous command or query and/or retrieves the response to

2702 ni.com
 Functions

a previous query.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mode (x200: 16-bit cmd) —

mode specifies whether to issue a command and/or retrieve a response.

Note The mode you specify can cause all or part of the command or response
parameters to be ignored. The possible results of specifying a particular mode are the
following:
• If mode specifies sending a 16-bit command, the upper half of command is
ignored.
• If mode specifies retrieving a response only, command is ignored.
• If mode specifies sending a command only, response is ignored.
• If mode specifies to retrieve a 16-bit value, the upper half of response is set to
0.

This input accepts the following values.

0x0002 Get 16-bit Response From Previous Query

0x0004 Get 32-bit Response From Previous Query
0x0200 Send 16-bit Command
0x0202 Send 16-bit Query; Get 16-bit Response
0x0400 Send 32-bit Command
0x0402 Send 32-bit Query; Get 16-bit Response
0x0404 Send 32-bit Query; Get 32-bit Response

• command —

command is the miscellaneous command to send.

© National Instruments 2703

 Functions

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• response —

response is the response retrieved from the device.

If the mode specifies to send a command rather than retrieve a response, you can use VI_NULL
for this parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Assert Interrupt Signal Function

Asserts the specified device interrupt or signal.

In VXI, for example, this can be done with either a VXI signal or a VXI interrupt. On
certain bus types, statusID may be ignored.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• mode —

2704 ni.com
 Functions

mode specifies how to assert the interrupt.

This input accepts the following values.

–1 VXI Signal—Send the notification using a VXI signal.

0 Assigned Method—Use the notification method assigned to the local device.
VXI/VME IRQ1–VXI/VME IRQ7—Send the interrupt through the specified VXI/VME IRQ line.
1–7 This uses the standard VXI/VME ROAK (release on acknowledge) interrupt mechanism rather
than the older VME RORA (release on register access) mechanism.

• status ID —

status ID is the status value to be presented during an interrupt acknowledge cycle.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Note VISA Assert Interrupt Signal does not accept VISA sessions of class
Instr. The VISA session must be of class VXI/GPIB-VXI Backplane or VXI
Servant.

VISA Assert Utility Signal Function

Asserts or deasserts the specified utility bus signal.

© National Instruments 2705

 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• bus signal —

bus signal specifies the utility bus signal to assert.

This input accepts the following values.

1 Assert SYSRESET
2 Assert SYSFAIL
3 Deassert SYSFAIL

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

This function can assert the SYSFAIL or SYSRESET utility bus interrupts on the VXI
backplane.

Note VISA Assert Utility Signal does not accept VISA sessions of class Instr.
The VISA session must be of class VXI/GPIB-VXI Backplane or VXI Servant.

VISA Map Trigger Function

Maps the specified trigger source line to the specified trigger destination line.

2706 ni.com
 Functions

Inputs/Outputs
• mode —

mode is VI_NULL.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• trigger source —

trigger source is the source line from which to map.

This input accepts the following values.

0–7 VXI/PXI TTL Line 0–VXI/PXI TTL Line 7—Map the specified VXI TTL trigger line.
27 Front Panel Input—Map the controller's front panel trigger input line.
28 Front Panel Output—Map the controller's front panel trigger output line.
8 VXI ECL Line 0—Map the specified VXI ECL trigger line.
9 VXI ECL Line 1—Map the specified VXI ECL trigger line.

• trigger destination —

trigger destination is the destination line to which to map.

This input accepts the following values.

0–7 VXI/PXI TTL Line 0–VXI/PXI TTL Line 7—Map the specified VXI TTL trigger line.
27 Front Panel Input—Map the controller's front panel trigger input line.
28 Front Panel Output—Map the controller's front panel trigger output line.
8 VXI ECL Line 0—Map the specified VXI ECL trigger line.
9 VXI ECL Line 1—Map the specified VXI ECL trigger line.

• error in (no error) —

© National Instruments 2707

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Note VISA Map Trigger does not accept VISA sessions of class Instr. The VISA
session must be of class PXI Backplane or VXI/GPIB-VXI Backplane.

If this function is called multiple times on the same backplane resource with the same
trigger source line and different trigger destination lines, all of the specified trigger
destination lines are asserted when the trigger source line is asserted. If this function
is called multiple times on the same backplane resource with different trigger source
lines and the same trigger destination line, the trigger destination line is asserted
when any of the specified trigger source lines are asserted.

VISA Unmap Trigger Function

Unmaps a previous map from the specified trigger source line to the specified trigger
destination line. This function unmaps one trigger mapping per call.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also

2708 ni.com
 Functions

specifies the session and class.

• trigger source —

trigger source is the source line used in the previous map.

This input accepts the following values.

0–7 VXI/PXI TTL Line 0–VXI/PXI TTL Line 7—Unmap the specified trigger line.
27 Front Panel Input—Unmap the controller's front panel trigger input line.
28 Front Panel Output—Unmap the controller's front panel trigger output line.
8 VXI ECL Line 0—Unmap the specified VXI ECL trigger line.
9 VXI ECL Line 1—Unmap the specified VXI ECL trigger line.

• trigger destination (all) —

trigger destination is the destination line used in the previous map.

This input accepts the following values.

–2 All Connected Lines—Unmap all trigger lines to which the source is currently connected.
0–7 VXI/PXI TTL Line 0–VXI/PXI TTL Line 7—Unmap the specified VXI TTL trigger line.
27 Front Panel Input—Unmap the controller's front panel trigger input line.
28 Front Panel Output—Unmap the controller's front panel trigger output line.
8 VXI ECL Line 0—Unmap the specified VXI ECL trigger line.
9 VXI ECL Line 1—Unmap the specified VXI ECL trigger line.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

If VISA Map Trigger was previously called multiple times on the same backplane

© National Instruments 2709

 Functions

resource and created multiple mappings for either trigger source or trigger
destination, trigger mappings that you do not specify in trigger source or trigger
destination in this function remain in effect when the unmap operation completes.

Note This function does not accept VISA sessions of class Instr. The VISA
session must be of class PXI Backplane or VXI/GPIB-VXI Backplane.

VISA Write From File Function

Takes data from the file specified by filename and writes it to the device
synchronously.

filename opens in binary mode and the function reads the amount of data specified by
count. The data is then written to the device. This operation returns only when the
transfer terminates.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• filename —

filename is the name of file from which data will be read.

• count (entire file) —

count is the number of bytes to be written.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

2710 ni.com
 Functions

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• return count —

return count is the number of bytes actually transferred.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Read To File Function

Reads byte count synchronously and stores the transferred data in the file specified by
filename.

filename opens in binary mode. Any existing contents are destroyed if you set the
Message Based Settings:File Append Enable property to FALSE. The data is then
written to the file. The operation returns only when the transfer terminates.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• filename —

filename is the name of file to which data will be written.

• byte count —

byte count is the number of bytes to be read.

• error in (no error) —

© National Instruments 2711

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• return count —

return count is the number of bytes actually transferred.

• error out —

error out contains error information. This output provides standard error out functionality.

Event Handling

Use the Event Handling VIs and functions to use VISA events with your instruments.

The VIs and functions on this palette can return VISA error codes.

You also can access the Select Event Type constant from this palette.

Palette
Description
Object
VISA Enable
Event Enables notification of a specified event type.
Function
VISA Wait on
Suspends execution of an application thread and waits for an event type for a time
Event
period not to exceed that specified by timeout.
Function
VISA Disable
Event Disables servicing of an event.
Function
VISA Discard Discards all pending occurrences of the specified event type and mechanism from

2712 ni.com
 Functions

Palette
Description
Object
Events
the specified session.
Function

Waits for a service request from a device. Before you call this VI, first enable the
Wait for RQS event by calling the VISA Enable Event function and specifying Service Request as
the event type.

Select Event
Use this control to select the desired event type.
Type VI

VISA Enable Event Function

Enables notification of a specified event type.

Note You must call the VISA Enable Event function for a session before using
the VISA Wait on Event function.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• event type —

event type is the logical event identifier.

You can select from the following VISA event types.

© National Instruments 2713

 Functions

Service Request (default) 0x3FFF200B

Trigger 0xBFFF200A
Clear 0x3FFF200D
VXI Signal 0x3FFF2020
VXI/VME Interrupt 0xBFFF2021
VXI/VME Sysfail 0x3FFF201D
VXI/VME Sysreset 0x3FFF201E
GPIB CIC 0x3FFF2012
GPIB Talk 0x3FFF2013
GPIB Listen 0x3FFF2014
PXI Interrupt 0x3FFF2022
Serial Break 0x3FFF2023
Serial TermChar 0x3FFF2024
Serial CTS 0x3FFF2029
Serial DSR 0x3FFF202A
Serial DCD 0x3FFF202C
Serial RI 0x3FFF202E
Serial Character 0x3FFF2035
USB Interrupt 0x3FFF2037
All Enabled 0x3FFF7FFF

Refer to the NI-VISA Help for more information about event types.

• mechanism (1: VI_QUEUE) —

mechanism specifies the event handling mechanism to be disabled.

Currently only accepts VI_QUEUE (1).

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

2714 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Detect Serial Break

Event.vi
• labview\examples\Instrument IO\GPIB\SRQ Event Handling.vi

VISA Wait on Event Function

Suspends execution of an application thread and waits for an event type for a time
period not to exceed that specified by timeout.

Inputs/Outputs
• timeout (0) —

timeout specifies the time, in milliseconds, that the function waits for the event.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• event type (all enabled) —

event type is the logical event identifier.

You can select from the following VISA event types.

Service Request 0x3FFF200B

Trigger 0xBFFF200A
Clear 0x3FFF200D

© National Instruments 2715

 Functions

VXI Signal 0x3FFF2020

VXI/VME Interrupt 0xBFFF2021
VXI/VME Sysfail 0x3FFF201D
VXI/VME Sysreset 0x3FFF201E
GPIB CIC 0x3FFF2012
GPIB Talk 0x3FFF2013
GPIB Listen 0x3FFF2014
PXI Interrupt 0x3FFF2022
Serial Break 0x3FFF2023
Serial TermChar 0x3FFF2024
Serial CTS 0x3FFF2029
Serial DSR 0x3FFF202A
Serial DCD 0x3FFF202C
Serial RI 0x3FFF202E
Serial Character 0x3FFF2035
USB Interrupt 0x3FFF2037
All Enabled (default) 0x3FFF7FFF

Refer to the NI-VISA Help for more information about event types.

• event class (Generic Event) —

event class specifies the class of event for which the function waits. The default is Generic
Event, meaning the function recognizes any class of event.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• event type out —

event type out identifies the event type received if the wait was successful.

• event —

event is valid if the wait was successful.

2716 ni.com
 Functions

Wire event to a Property Node to get further information about the event. Wire event to the VISA
Close function when examination of the event is complete.
• error out —

error out contains error information. This output provides standard error out functionality.

You can set this function to perform I/O operations synchronously or asynchronously.
By default, the function handles I/O operations asynchronously. Right-click the
function and select Synchronous I/O Mode»Synchronous from the shortcut menu to
synchronously wait for an occurrence of the specified event.

Note In most applications, synchronous calls are slightly faster when you
are communicating with 4 or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with 5
or more instruments. The LabVIEW default is asynchronous I/O.

Refer to individual event descriptions for context definitions. If the specified event
type is All Events (0x3FFF7FFF), the operation waits for any event that is enabled for
the given session.

Note You must call the VISA Enable Event function for a given session before
using the VISA Wait on Event function.

If a session's event queue becomes full and a new event arrives, the new event is
discarded. The default event queue size per session is 50. If you expect more than 50
unhandled events to arrive, you can use the General Settings:Maximum Queue Length
property to set event queue size programmatically.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Detect Serial Break

Event.vi

© National Instruments 2717

 Functions

VISA Disable Event Function

Disables servicing of an event.

This operation prevents new event occurrences from being queued. However, event
occurrences already queued are not lost. Use the VISA Discard Events VI to discard
queued events.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• event type (all enabled) —

event type is the logical event identifier.

You can select from the following VISA event types.

Service Request 0x3FFF200B

Trigger 0xBFFF200A
Clear 0x3FFF200D
VXI Signal 0x3FFF2020
VXI/VME Interrupt 0xBFFF2021
VXI/VME Sysfail 0x3FFF201D
VXI/VME Sysreset 0x3FFF201E
GPIB CIC 0x3FFF2012
GPIB Talk 0x3FFF2013
GPIB Listen 0x3FFF2014
PXI Interrupt 0x3FFF2022
Serial Break 0x3FFF2023
Serial TermChar 0x3FFF2024

2718 ni.com
 Functions

Serial CTS 0x3FFF2029

Serial DSR 0x3FFF202A
Serial DCD 0x3FFF202C
Serial RI 0x3FFF202E
Serial Character 0x3FFF2035
USB Interrupt 0x3FFF2037
All Enabled (default) 0x3FFF7FFF

Refer to the NI-VISA Help for more information about event types.

• mechanism (1: VI_QUEUE) —

mechanism specifies the event handling mechanism to be disabled.

Currently only accepts VI_QUEUE (1).

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\GPIB\SRQ Event Handling.vi

VISA Discard Events Function

Discards all pending occurrences of the specified event type and mechanism from the
specified session.

© National Instruments 2719

 Functions

This function discards information about all the event occurrences that have not yet
been handled. This behavior is useful if you want to remove event occurrences that an
operation no longer needs. Discarded event occurrences are not available to a session
at a later time.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• event type (all enabled) —

event type is the logical event identifier.

You can select from the following VISA event types.

Service Request 0x3FFF200B

Trigger 0xBFFF200A
Clear 0x3FFF200D
VXI Signal 0x3FFF2020
VXI/VME Interrupt 0xBFFF2021
VXI/VME Sysfail 0x3FFF201D
VXI/VME Sysreset 0x3FFF201E
GPIB CIC 0x3FFF2012
GPIB Talk 0x3FFF2013
GPIB Listen 0x3FFF2014
PXI Interrupt 0x3FFF2022
Serial Break 0x3FFF2023
Serial TermChar 0x3FFF2024
Serial CTS 0x3FFF2029
Serial DSR 0x3FFF202A
Serial DCD 0x3FFF202C
Serial RI 0x3FFF202E

2720 ni.com
 Functions

Serial Character 0x3FFF2035

USB Interrupt 0x3FFF2037
All Enabled (default) 0x3FFF7FFF

Refer to the NI-VISA Help for more information about event types.

• mechanism (1: VI_QUEUE) —

mechanism specifies the event handling mechanism to be disabled.

Currently only accepts VI_QUEUE (1).

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Detect Serial Break

Event.vi

Wait for RQS

Waits for a service request from a device. Before you call this VI, first enable the event
by calling the VISA Enable Event function and specifying Service Request as the event
type.

If the event arrives within the specified timeout period, the status byte of the device is

© National Instruments 2721

 Functions

read and returned.

Inputs/Outputs
• timeout (25000 ms) —

timeout specifies the time, in milliseconds, that the VI waits for the event. The default is 25,000
ms.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• status byte —

status byte is returned if the event arrives within the specified timeout period.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\GPIB\SRQ Event Handling.vi

2722 ni.com
 Functions

Select Event Type VI

Use this control to select the desired event type.

Data type
• —

Service Request 3FFF200B

Trigger BFFF200A
Clear 3FFF200D
VXI Signal 3FFF2020
VXI/VME Interrupt BFFF2021
VXI/VME Sysfail 3FFF201D
VXI/VME Sysreset 3FFF201E
GPIB CIC 3FFF2012
GPIB Talk 3FFF2013
GPIB Listen 3FFF2014
PXI Interrupt 3FFF2022
Serial Break 3FFF2023
Serial TermChar 3FFF2024
Serial CTS 3FFF2029
Serial DSR 3FFF202A
Serial DCD 3FFF202C
Serial RI 3FFF202E
Serial Character 3FFF2035
USB Interrupt 3FFF2037

© National Instruments 2723

 Functions

All Enabled 3FFF7FFF

VISA Lock Async

Asynchronously attempts to establish access to the device or interface specified by

VISA resource name. Use this function to obtain an exclusive lock that guarantees sole
access to a device or resource.

Inputs/Outputs
• lock type (exclusive: 1) —

lock type specifies the type of lock you want to request for the session. You can specify a value
of 1 or a 2 to mean an exclusive or shared lock, respectively. The default value is 1.

If a session has an exclusive lock, other sessions cannot modify global attributes or invoke
operations but still can get attributes and set local attributes. If the session has a shared lock,
other sessions that have shared locks also can modify global attributes and invoke operations.

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• timeout (0) —

timeout specifies the time, in milliseconds, that the function waits for access to lock.

• requested key —

requested key specifies a unique access key for the shared lock. This parameter is valid only if
you specify a value of 2 for the lock type parameter.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

2724 ni.com
 Functions

standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• access key —

access key returns a unique access key for the lock if this VI runs successfully. You then can share
the lock by wiring this output to other sessions. access key is valid only if you specify a value of 2
for the lock type parameter.

• error out —

error out contains error information. This output provides standard error out functionality.

You also can obtain shared locks. The locking mechanism works for all processes and
resources that exist on the same computer. Refer to the NI-VISA Help topic on the
viLock function for more information about requesting keys and lock sharing.

If a locked VISA session is closed without first being unlocked, VISA automatically
performs a VISA Unlock operation on that session, regardless of the type of lock set on
the session.

VISA Unlock Function

Relinquishes the lock previously obtained using the VISA Lock Async function.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

© National Instruments 2725

 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\VISA\Locking\VISA
Locking.vi

Register Access

Use the Register Access functions to program in an address space at a high level.

The functions on this palette can return VISA error codes.

Palette Object Description

VISA In 8 Function Reads an 8-bit block of data from the specified address space and offset.
VISA In 16
Reads a 16-bit block of data from the specified address space and offset.
Function
VISA In 32
Reads a 32-bit block of data from the specified address space and offset.
Function
VISA In 64
Reads a 64-bit block of data from the specified address space and offset.
Function
VISA Out 8 Writes an 8-bit block of data to the specified address space and offset.

2726 ni.com
 Functions

Palette Object Description

Function
VISA Out 16
Writes a 16-bit block of data to the specified address space and offset.
Function
VISA Out 32
Writes a 32-bit block of data to the specified address space and offset.
Function
VISA Out 64
Writes a 64-bit block of data to the specified address space and offset.
Function
VISA Move In 8
Moves one or more 8-bit units of data from device memory to local memory.
Function
VISA Move In 16
Moves one or more 16-bit units of data from device memory to local memory.
Function
VISA Move In 32
Moves one or more 32-bit units of data from device memory to local memory.
Function
VISA Move In 64
Moves one or more 64-bit units of data from device memory to local memory.
Function
VISA Move Out 8 Moves an array of 8-bit data from local memory to the specified address space
Function and offset.
VISA Move Out 16 Moves an array of 16-bit data from local memory to the specified address space
Function and offset.
VISA Move Out 32 Moves an array of 32-bit data from local memory to the specified address space
Function and offset.
VISA Move Out 64 Moves an array of 64-bit data from local memory to the specified address space
Function and offset.
VISA Memory
Allocates device memory of a specified size and returns the offset that specifies
Allocation
where the memory is located.
Function
VISA Memory
Allocates device memory of a specified size and returns the offset that specifies
Allocation Ex
where the memory is located.
Function
VISA Memory Free Frees the memory previously allocated by the VISA Memory Allocation function
Function or the VISA Memory Allocation Ex function.
VISA Move Moves length elements of the given source width from the specified source
Function address space and offset to the specified destination address space and offset.

© National Instruments 2727

 Functions

Palette Object Description

Low Level Use the Low Level Register Access functions to program in an address space
Register Access with more detail than is provided at a high level.

VISA In 8 Function
Reads an 8-bit block of data from the specified address space and offset.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space without requiring VISA Map Address to be called. The
following table lists the valid entries for specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

2728 ni.com
 Functions

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA In 8, VISA In 16, VISA In 32, and VISA In 64
operations for an INSTR Resource is the offset address relative to the device's allocated
address base for the corresponding address space that was specified. For example, if
address space specifies VXI/VME A16, offset specifies the offset from the logical address
base address of the specified VXI device. If address space specifies VXI/VME A24, A32, or A64,
offset specifies the offset from the base address of the VXI device's memory space allocated
by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the data read from address space.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA In 16 Function
Reads a 16-bit block of data from the specified address space and offset.

© National Instruments 2729

 Functions

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space without requiring VISA Map Address to be called. The
following table lists the valid entries for specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA In 8, VISA In 16, VISA In 32, and VISA In 64
operations for an INSTR Resource is the offset address relative to the device's allocated
address base for the corresponding address space that was specified. For example, if
address space specifies VXI/VME A16, offset specifies the offset from the logical address

2730 ni.com
 Functions

base address of the specified VXI device. If address space specifies VXI/VME A24, A32, or A64,
offset specifies the offset from the base address of the VXI device's memory space allocated
by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the data read from address space.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA In 32 Function
Reads a 32-bit block of data from the specified address space and offset.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space without requiring VISA Map Address to be called. The
following table lists the valid entries for specifying address space.

© National Instruments 2731

 Functions

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA In 8, VISA In 16, VISA In 32, and VISA In 64
operations for an INSTR Resource is the offset address relative to the device's allocated
address base for the corresponding address space that was specified. For example, if
address space specifies VXI/VME A16, offset specifies the offset from the logical address
base address of the specified VXI device. If address space specifies VXI/VME A24, A32, or A64,
offset specifies the offset from the base address of the VXI device's memory space allocated
by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

2732 ni.com
 Functions

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the data read from address space.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA In 64 Function
Reads a 64-bit block of data from the specified address space and offset.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space without requiring VISA Map Address to be called. The
following table lists the valid entries for specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI PXI Memory Allocations (9)

© National Instruments 2733

 Functions

Value Description

PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA In 8, VISA In 16, VISA In 32, and VISA In 64
operations for an INSTR Resource is the offset address relative to the device's allocated
address base for the corresponding address space that was specified. For example, if
address space specifies VXI/VME A16, offset specifies the offset from the logical address
base address of the specified VXI device. If address space specifies VXI/VME A24, A32, or A64,
offset specifies the offset from the base address of the VXI device's memory space allocated
by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the read data.

• error out —

error out contains error information. This output provides standard error out functionality.

2734 ni.com
 Functions

VISA Out 8 Function

Writes an 8-bit block of data to the specified address space and offset.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

© National Instruments 2735

 Functions

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA Out 8, VISA Out 16, VISA Out 32, and VISA
Out 64 operations for an INSTR Resource is the offset address relative to the device's
allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the specified VXI device. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• value (0) —

value contains the data to write to address space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Out 16 Function

Writes a 16-bit block of data to the specified address space and offset.

2736 ni.com
 Functions

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA Out 8, VISA Out 16, VISA Out 32, and VISA
Out 64 operations for an INSTR Resource is the offset address relative to the device's
allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the specified VXI device. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

© National Instruments 2737

 Functions

• value (0) —

value contains the data to write to address space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Out 32 Function

Writes a 32-bit block of data to the specified address space and offset.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI, VME, and GPIB-VXI
VXI/VME A24 (2)

2738 ni.com
 Functions

Value Description

VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA Out 8, VISA Out 16, VISA Out 32, and VISA
Out 64 operations for an INSTR Resource is the offset address relative to the device's
allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the specified VXI device. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• value (0) —

value contains the data to write to address space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

© National Instruments 2739

 Functions

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Out 64 Function

Writes a 64-bit block of data to the specified address space and offset.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI
PXI Configuration (10)

2740 ni.com
 Functions

Value Description

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to read from.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.
• INSTR Specific—The offset specified in the VISA Out 8, VISA Out 16, VISA Out 32, and VISA
Out 64 operations for an INSTR Resource is the offset address relative to the device's
allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the specified VXI device. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32 or A64 space.
• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.
• value (0) —

value contains the value to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2741

 Functions

VISA Move In 8 Function

Moves one or more 8-bit units of data from device memory to local memory.

This function uses the specified address space and offset to read in count 8-bit units of
data.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also

2742 ni.com
 Functions

specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move In 8, VISA Move In 16, VISA Move In 32,
and VISA Move In 64 operations for an INSTR Resource is the offset address relative to the
device's allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the VXI device specified. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move In XX operations for an INSTR Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move In XX operations for a MEMACC Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• count —

count is the number of data items to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• data —

data is the array of 8 bit data being moved.

© National Instruments 2743

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move In 16 Function

Moves one or more 16-bit units of data from device memory to local memory.

This function uses the specified address space and offset to read in count 16-bit units
of data.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI
PXI Configuration (10)

2744 ni.com
 Functions

Value Description

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move In 8, VISA Move In 16, VISA Move In 32,
and VISA Move In 64 operations for an INSTR Resource is the offset address relative to the
device's allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the VXI device specified. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move In XX operations for an INSTR Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move In XX operations for a MEMACC Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• count —

count is the number of data items to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

© National Instruments 2745

 Functions

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• data —

data is the array of 16 bit data being moved.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move In 32 Function

Moves one or more 32-bit units of data from device memory to local memory.

This function uses the specified address space and offset to read in count 32-bit units
of data.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI, VME, and GPIB-VXI
VXI/VME A24 (2)

2746 ni.com
 Functions

Value Description

VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to write to.

offset accepts a 32- or 64-bit unsigned integer as input. The type of resource determines how
offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move In 8, VISA Move In 16, VISA Move In 32,
and VISA Move In 64 operations for an INSTR Resource is the offset address relative to the
device's allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the VXI device specified. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move In XX operations for an INSTR Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move In XX operations for a MEMACC Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the

© National Instruments 2747

 Functions

specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• count —

count is the number of data items to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• data —

data is the array of 32 bit data being moved.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move In 64 Function

Moves one or more 64-bit units of data from device memory to local memory.

This function uses the specified address space and offset to read in count 64-bit units
of data.

Inputs/Outputs
• address space (A16: 1) —

2748 ni.com
 Functions

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset, in bytes, of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move In 8, VISA Move In 16, VISA Move In 32,
and VISA Move In 64 operations for an INSTR Resource is the offset address relative to the
device's allocated address base for the corresponding address space that was specified. For
example, if address space specifies VXI/VME A16, offset specifies the offset from the logical
address base address of the VXI device specified. If address space specifies VXI/VME A24,
A32, or A64, offset specifies the offset from the base address of the VXI device's memory
space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move In XX operations for an INSTR Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

© National Instruments 2749

 Functions

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move In XX operations for a MEMACC Resource is the number
of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• count —

count is the number of data items to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• data —

data is the array of 64-bit data being moved.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move Out 8 Function

Moves an array of 8-bit data from local memory to the specified address space and
offset.

2750 ni.com
 Functions

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset (in bytes) of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move Out 8, VISA Move Out 16, VISA Move
Out 32, and VISA Move Out 64 operations for an INSTR Resource is the offset address relative
to the device's allocated address base for the corresponding address space that was
specified. For example, if address space specifies VXI/VME A16, offset specifies the offset
from the logical address base address of the VXI device specified. If address space specifies
VXI/VME A24, A32, or A64, offset specifies the offset from the base address of the VXI device's
memory space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move Out XX operations for an INSTR Resource is the

© National Instruments 2751

 Functions

number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move Out XX operations for a MEMACC Resource is the
number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• data —

data is the data you want to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move Out 16 Function

Moves an array of 16-bit data from local memory to the specified address space and
offset.

2752 ni.com
 Functions

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map.

The following table lists the valid entries for specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset (in bytes) of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move Out 8, VISA Move Out 16, VISA Move
Out 32, and VISA Move Out 64 operations for an INSTR Resource is the offset address relative
to the device's allocated address base for the corresponding address space that was
specified. For example, if address space specifies VXI/VME A16, offset specifies the offset
from the logical address base address of the VXI device specified. If address space specifies
VXI/VME A24, A32, or A64, offset specifies the offset from the base address of the VXI device's
memory space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

© National Instruments 2753

 Functions

The count specified in the VISA Move Out XX operations for an INSTR Resource is the
number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move Out XX operations for a MEMACC Resource is the
number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• data —

data is the data you want to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move Out 32 Function

Moves an array of 32-bit data from local memory to the specified address space and
offset.

2754 ni.com
 Functions

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset (in bytes) of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move Out 8, VISA Move Out 16, VISA Move
Out 32, and VISA Move Out 64 operations for an INSTR Resource is the offset address relative
to the device's allocated address base for the corresponding address space that was
specified. For example, if address space specifies VXI/VME A16, offset specifies the offset
from the logical address base address of the VXI device specified. If address space specifies
VXI/VME A24, A32, or A64, offset specifies the offset from the base address of the VXI device's
memory space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move Out XX operations for an INSTR Resource is the

© National Instruments 2755

 Functions

number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move Out XX operations for a MEMACC Resource is the
number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• data —

data is the data you want to move.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Move Out 64 Function

Moves an array of 64-bit data from local memory to the specified address space and
offset.

2756 ni.com
 Functions

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for
specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset is the offset (in bytes) of the device to write to. offset accepts a 32- or 64-bit unsigned
integer as input. The type of resource determines how offset specifies the offset.

• INSTR Specific—The offset specified in the VISA Move Out 8, VISA Move Out 16, VISA Move
Out 32, and VISA Move Out 64 operations for an INSTR Resource is the offset address relative
to the device's allocated address base for the corresponding address space that was
specified. For example, if address space specifies VXI/VME A16, offset specifies the offset
from the logical address base address of the VXI device specified. If address space specifies
VXI/VME A24, A32, or A64, offset specifies the offset from the base address of the VXI device's
memory space allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64.

The count specified in the VISA Move Out XX operations for an INSTR Resource is the

© National Instruments 2757

 Functions

number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the amount of memory
exported by the device in the given space.

• MEMACC Specific—For a MEMACC Resource, offset specifies an absolute address.

The count specified in the VISA Move Out XX operations for a MEMACC Resource is the
number of data items (of the size corresponding to the operation) to move, beginning at the
specified offset. Therefore, offset + count*size cannot exceed the total amount of memory
available in the given space.

• data —

data is the array of 64-bit data being moved.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Memory Allocation Function

Allocates device memory of a specified size and returns the offset that specifies where
the memory is located.

Inputs/Outputs
• VISA resource name —

2758 ni.com
 Functions

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• size —

size specifies the size of the allocation.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• offset —

offset is a 32-bit offset which specifies the location of the allocated memory.

• error out —

error out contains error information. This output provides standard error out functionality.

The memory can be allocated on either the device itself or on the computer's system
memory. If the device to which the given VISA Session refers is located on the local
interface card, the memory can be allocated either on the device itself or on the
computer's system memory. The memory region referenced by offset that is returned
from this function can be accessed with the high-level functions VISA Move In 8, VISA
Move In 16, VISA Move In 32, VISA Move In 64, VISA Move Out 8, VISA Move Out 16, VISA
Move Out 32, and VISA Move Out 64 or it can be mapped using the VISA Map Address
function.

VISA Memory Allocation Ex Function

Allocates device memory of a specified size and returns the offset that specifies where
the memory is located.

© National Instruments 2759

 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• size —

size specifies the size of the allocation.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• offset —

offset is a 64-bit offset which specifies the location of the allocated memory.

• error out —

error out contains error information. This output provides standard error out functionality.

The memory can be allocated on either the device itself or on the computer's system
memory. If the device to which the given VISA Session refers is located on the local
interface card, the memory can be allocated either on the device itself or on the
computer's system memory. The memory region referenced by offset that is returned
from this function can be accessed with the high-level functions VISA Move In 8, VISA
Move In 16, VISA Move In 32, VISA Move In 64, VISA Move Out 8, VISA Move Out 16, VISA
Move Out 32, and VISA Move Out 64 or it can be mapped using the VISA Map Address
function.

2760 ni.com
 Functions

Note The offset of this function could be above the 4 GB boundary. If your
device cannot access this memory, use the VISA Memory Allocation function
instead.

VISA Memory Free Function

Frees the memory previously allocated by the VISA Memory Allocation function or the
VISA Memory Allocation Ex function.

If the specified offset has been mapped using the VISA Map Address function, you
must unmap the offset using the VISA Unmap Address function before the memory can
be freed.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset —

offset specifies the memory previously allocated by the VISA Memory Allocation function or the
VISA Memory Allocation Ex function.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

© National Instruments 2761

 Functions

error out contains error information. This output provides standard error out functionality.

VISA Move Function

Moves length elements of the given source width from the specified source address
space and offset to the specified destination address space and offset.

Inputs/Outputs
• source width (16-bit: 2) —

source width specifies the width of the source data.

This input accepts the following values.

1 8-bit
2 16-bit (default)
4 32-bit

• source space (A16: 1) —

source space specifies the address space of the data to be moved.

Refer to the table listed under address space in the VISA In 8 function for more information.

1 VXI/VME A16
2 VXI/VME A24
3 VXI/VME A32

2762 ni.com
 Functions

4 VXI/VME A64

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• source offset (0) —

source offset is the offset (in bytes) of the device to read from.

It is the offset address relative to the device's allocated address base for the corresponding
specified address space. For example, if source space specifies VXI/VME A16, source offset
specifies the offset from the logical address base address of the VXI device specified. If source
space specifies VXI/VME A24, A32, or A64, source offset specifies the offset from the base address
of the VXI device's memory space allocated by the VXI Resource Manager within VXI A24 or A32.

• length —

length specifies the number of elements to move.

• dest offset (0) —

dest offset is the offset, in bytes, of the destination device.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• dest space (A16: 1) —

dest space specifies the address space of the destination.

Refer to the table listed under source space for more information.

• dest width (same as source) —

dest width specifies the width of the destination data.

If dest width is not wired, it will be the same as the source width. This input accepts the
following values.

© National Instruments 2763

 Functions

1 8-bit
2 16-bit (default)
4 32-bit

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Note This function does not accept all classes of VISA sessions. Valid VISA
session classes include GPIB-VXI INSTR, GPIB-VXI MEMACC, VXI INSTR, and VXI
MEMACC.

Low Level Register Access

Use the Low Level Register Access functions to program in an address space with more
detail than is provided at a high level.

The functions on this palette can return VISA error codes.

Palette Object Description

VISA Map Address
Maps a memory space specified by map base and map size.
Function
VISA Unmap Unmaps the memory space previously mapped by the VISA Map Address
Address Function function.
VISA Peek 8
Reads an 8-bit value from the address location specified in offset.
Function
VISA Peek 16 Reads a 16-bit value from the address location specified by offset.

2764 ni.com
 Functions

Palette Object Description

Function
VISA Peek 32
Reads a 32-bit value from the address location specified in offset.
Function
VISA Peek 64
Reads a 64-bit value from the address location specified in offset.
Function
VISA Poke 8 Writes an 8-bit value to the specified address and stores the content of the
Function value to the address pointed to by offset.
VISA Poke 16 Writes a 16-bit value to the specified address and stores the content of the
Function value to the address pointed to by offset.
VISA Poke 32 Writes a 32-bit value to the specified address and stores the content of the
Function value to the address pointed to by offset.
VISA Poke 64 Writes a 64-bit value to the specified address and stores the content of the
Function value to the address pointed to by offset.

VISA Map Address Function

Maps a memory space specified by map base and map size.

The memory space that the function maps depends on the type of interface specified
by VISA resource name and address space. After the window is mapped, VISA keeps
track of the window that is mapped. This dictates that VISA can map only one window
for each VISA session.

Inputs/Outputs
• address space (A16: 1) —

address space specifies the address space to map. The following table lists the valid entries for

© National Instruments 2765

 Functions

specifying address space.

Value Description

VXI/VME A16 (1)

VXI/VME A24 (2)

VXI, VME, and GPIB-VXI
VXI/VME A32 (3)

VXI/VME A64 (4)

PXI Memory Allocations (9)

PXI PXI Configuration (10)

PXI BAR0 (11) to PXI BAR5 (16)

• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• map base (0) —

map base contains the offset (in bytes) of the memory to be mapped.

The type of resource determines how map base specifies the offset.
• INSTR Specific—Notice that map base specified in the VISA Map Address operation for an
INSTR Resource is the offset address relative to the device's allocated address base for the
corresponding address space that was specified. For example, if address space specifies
VXI/VME A16, map base specifies the offset from the logical address base address of the
specified VXI device. If address space specifies VXI/VME A24, VXI/VME A32, or VXI/VME A64,
map base specifies the offset from the base address of the VXI device's memory space
allocated by the VXI Resource Manager within VXI/VME A24, A32, or A64 space.
• MEMACC Specific—For a MEMACC Resource, map base specifies an absolute address.
• map size (0) —

map size contains the amount of memory to map.

• error in (no error) —

2766 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• access (False) —

access is reserved for future use and should be set to FALSE.

This input is available only if you do not place a checkmark in the Restrict Access checkbox on
the Configuration page of the Properties dialog box for the variable refnum.
• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Unmap Address Function

Unmaps the memory space previously mapped by the VISA Map Address function.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

© National Instruments 2767

 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

VISA Peek 8 Function

Reads an 8-bit value from the address location specified in offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the read data.

• error out —

2768 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Peek 16 Function

Reads a 16-bit value from the address location specified by offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

© National Instruments 2769

 Functions

• value —

value contains the read data.

• error out —

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Peek 32 Function

Reads a 32-bit value from the address location specified in offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides

2770 ni.com
 Functions

standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the read data.

• error out —

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Peek 64 Function

Reads a 64-bit value from the address location specified in offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

© National Instruments 2771

 Functions

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• value —

value contains the read data.

• error out —

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Poke 8 Function

Writes an 8-bit value to the specified address and stores the content of the value to the
address pointed to by offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

2772 ni.com
 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• value (0) —

value contains the value to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Poke 16 Function

Writes a 16-bit value to the specified address and stores the content of the value to the
address pointed to by offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

© National Instruments 2773

 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• value (0) —

value contains the value to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

2774 ni.com
 Functions

VISA Poke 32 Function

Writes a 32-bit value to the specified address and stores the content of the value to the
address pointed to by offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• value (0) —

value contains the value to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2775

 Functions

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Poke 64 Function

Writes a 64-bit value to the specified address and stores the content of the value to the
address pointed to by offset.

You must use the VISA Map Address function to map the address before you call this
function. The address must be a valid memory address in the current process.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• offset (0) —

offset contains the offset, in bytes, from the register location originally mapped in the mapped
memory space.

• value (0) —

value contains the value to write.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

2776 ni.com
 Functions

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

If you use NI I/O Trace to debug this function, enable the Force peek/poke calls to
appear in NI I/O Trace option in Measurement & Automation Explorer (Windows),
visaconf (Linux), or NI-VISA Configuration (Mac OS X). If you do not enable this
function, NI I/O Trace might not log this function.

VISA Clear Function

Clears the input and output buffers of the device.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2777

 Functions

Clear for 488.2 Instruments (GPIB, VXI, TCP/IP, USB)

• GPIB—VISA sends the Selected Device Clear command.

• VXI—VISA sends the Word Serial Clear command.
• USB—VISA sends the INITIATE_CLEAR and CHECK_CLEAR_STATUS commands on
the control pipe.

Clear for Non-488.2 Instruments (Serial Instr, TCP/IP Socket, USB Raw)

• Serial Instr—VISA flushes (discards) the I/O output buffer, sends a break, and then
flushes the I/O input buffer.
• TCP/IP Socket—VISA flushes the I/O buffers.
• USB Raw—VISA resets the endpoints referred to by the USB Settings:Bulk-In Pipe
and USB Settings:Out Pipe properties.

VISA Read STB Function

Reads a service request status byte byte from the message-based device specified by
VISA resource name.

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

2778 ni.com
 Functions

• status byte —

status byte contains the status byte read from the instrument.

• error out —

error out contains error information. This output provides standard error out functionality.

Status Bytes for 488.2 Instruments (GPIB, VXI, TCP/IP, USB)

This function reads a service request from a message-based device. The following
details are bus-specific:

• GPIB—This function reads the status by serial polling the device.

• VXI—This function sends the Word Serial Read STB query to the device.
• USB—This function sends the device the Read Status Byte command on the control
pipe.

Status Bytes for Non-488.2 Instruments (Serial Instr, TCP/IP Socket, USB
Raw)

This function retrieves status information by sending a message in response to a

service request. For a session to a Serial Instr or Ethernet Socket, if the property IO
Protocol is Serial-TCPIP/488 (4), the device is sent the string "*STB?\n" and then the
device status byte is read; otherwise, this operation is not valid.

VISA Assert Trigger Function

Asserts a software or hardware trigger, depending on the interface type. For software
triggers, Default (0) is the only valid protocol. For VXI hardware triggers, Default (0) is
equivalent to Sync (5). For PXI triggers, PXI: Reserve (6) and PXI: Unreserve (7) are the
only valid protocols.

© National Instruments 2779

 Functions

Inputs/Outputs
• VISA resource name —

VISA resource name specifies the resource to be opened. The VISA resource name control also
specifies the session and class.

• protocol (default: 0) —

protocol is the trigger protocol to use during assertion.

This input accepts the following values.

0 Default
1 On
2 Off
5 Sync
6 PXI: Reserve
7 PXI: Unreserve

• error in (no error) —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• VISA resource name out —

VISA resource name out is a copy of the VISA resource name that VISA functions return.

• error out —

error out contains error information. This output provides standard error out functionality.

Software Triggers for 488.2 Instruments (GPIB, VXI, TCP/IP, USB)

This function sends an IEEE-488.2 software trigger to the addressed device, with the
following bus-specific details:

• GPIB—VISA addresses the device to listen and sends the GPIB Group Execute
Trigger (GET) message.
• VXI—VISA sends the Word Serial Trigger command.

2780 ni.com
 Functions

• USB—VISA sends the trigger message ID on the bulk-out pipe.

Software Triggers for Non-488.2 Instruments (Serial Instr, TCP/IP Socket,

USB Raw)

If the property IO Protocol is set to Serial-TCPIP-USB/488 Strings (4), this function

sends the string "*TRG\n" to the device. Otherwise, this operation is not valid.

Hardware Triggers for VXI

For hardware triggers to VXI instruments, you must first set the property Trigger
Identifier to the desired trigger line. This function performs the specified trigger
operation on the line identified by the Trigger Identifier property.

Trigger Reservation for PXI

For PXI instruments, this function reserves or unreserves (releases) a trigger line for
use in external triggering.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\VISA\PXI\PXI - Reserve

Trigger.vi

GPIB
Use the GPIB functions to communicate with GPIB (IEEE-488) devices.

The functions on this palette can return specific GPIB error codes.

© National Instruments 2781

 Functions

Palette
Description
Object
GPIB Read
Reads byte count number of bytes from the GPIB device at address string.
Function
GPIB Write
Writes data to the GPIB device identified by address string.
Function
Wait for
GPIB RQS Waits for the device indicated by address string to assert RQS.
Function
GPIB Trigger
Sends GET (Group Execute Trigger) to the device indicated by address string.
Function
GPIB Clear
Sends either SDC (Selected Device Clear) or DCL (Device Clear).
Function
GPIB Serial
Poll Performs a serial poll of the device indicated by address string.
Function
GPIB
Initialization Configures the GPIB interface at address string.
Function
Shows the present status of the GPIB Controller indicated by address string. Error I/O
GPIB Status
operates uniquely in this function. The function gets the status of the GPIB Controller
Function
regardless of whether an error occurred in a preceding operation.
GPIB Wait Waits for the state(s) indicated by wait state vector at the device indicated by
Function address string.
GPIB Misc Performs the GPIB operation indicated by command string. Use this low-level
Function function when the other high-level, traditional GPIB functions are not suitable.

Use the GPIB 488.2 functions to exchange data and instructions between VIs and
GPIB 488.2
GPIB 488.2 devices.

Compatible GPIB Hardware

All NI-488.2 hardware drivers are compatible with LabVIEW. Refer to the GPIB Driver
Versions on the National Instruments Web site for information about current driver
versions for each GPIB controller.

2782 ni.com
 Functions

GPIB Read Function

Reads byte count number of bytes from the GPIB device at address string.

Right-click the node and select Synchronous I/O Mode»Synchronous from the
shortcut menu to read data synchronously.

Inputs/Outputs
• timeout ms (488.2 global) —

timeout ms specifies the time, in milliseconds, that the function waits before timing out.

The operation aborts if it does not complete within timeout ms. To disable timeouts, set
timeout ms to 0.

To use the 488.2 global timeout, leave timeout ms unwired or set the input to –1. Then use the
SetTimeOut function to change the default value of timeout ms. The default is 10000.

• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific

© National Instruments 2783

 Functions

function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• byte count —

byte count specifies the number of bytes the function reads from the GPIB device.

• mode (0) —

mode specifies conditions, other than reaching byte count, for terminating the read.

The following table includes valid values and the corresponding EOS characters. Any mode not
listed in the table indicates the decimal number of the EOS character that you want. Refer to
>GPIB Multiline Interface Messages for more information about managing GPIB tasks.

No EOS character. The EOS termination mode is disabled. Read terminated on EOI or byte
0
count.
1 EOS character is CR. Read terminated on EOI, byte count, or CR.
2 EOS character is LF. Read terminated on EOI, byte count, or LF.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data —

data is the data the function read.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active

2784 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

When you transfer data from or to a hardware driver synchronously, the calling thread
is locked for the duration of the data transfer. Depending on the speed of the transfer,
this can hinder other processes that require the calling thread. However, if an
application requires that the data transfer as quickly as possible, performing the
operation synchronously dedicates the calling thread exclusively to this operation.

Note In most applications, synchronous calls are slightly faster when you
are communicating with 4 or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with 5
or more instruments. The LabVIEW default is asynchronous I/O.

The GPIB Read function terminates when it accomplishes one of the following tasks:

• Reads the number of bytes requested.

• Detects an error.
• Exceeds the time limit.
• Detects the END message (EOI asserted).
• Detects the EOS character (if this option is enabled by the value supplied to mode).

Note The function compares all eight bits when it checks for the EOS

© National Instruments 2785

 Functions

character.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\GPIB\Simple GPIB.vi

GPIB Write Function

Writes data to the GPIB device identified by address string.

Right-click the node and select Synchronous I/O Mode»Synchronous from the
shortcut menu to write data synchronously.

Inputs/Outputs
• timeout ms (488.2 global) —

timeout ms specifies the time, in milliseconds, that the function waits before timing out.

The operation aborts if it does not complete within timeout ms. To disable timeouts, set
timeout ms to 0.

To use the 488.2 global timeout, leave timeout ms unwired or set the input to –1. Then use the
SetTimeOut function to change the default value of timeout ms. The default is 10000.

• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

2786 ni.com
 Functions

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• data —

data is the data the function writes to the GPIB device.

• mode (0) —

mode indicates how to terminate the GPIB Write.

This input accepts the following values.

0 Send EOI with the last character of the string.

1 Append CR to the string and send EOI with CR.
2 Append LF to the string and send EOI with LF.
3 Append CR LF to the string and send EOI with LF.
4 Append CR to the string but do not send EOI.
5 Append LF to the string but do not send EOI.
6 Append CR LF to the string but do not send EOI.
7 Do not send EOI.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table

© National Instruments 2787

 Functions

also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

When you transfer data from or to a hardware driver synchronously, the calling thread
is locked for the duration of the data transfer. Depending on the speed of the transfer,
this can hinder other processes that require the calling thread. However, if an
application requires that the data transfer as quickly as possible, performing the
operation synchronously dedicates the calling thread exclusively to this operation.

Note In most applications, synchronous calls are slightly faster when you
are communicating with 4 or fewer instruments. Asynchronous operations
result in a significantly faster application when you are communicating with 5
or more instruments. The LabVIEW default is asynchronous I/O.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\GPIB\Simple GPIB.vi

2788 ni.com
 Functions

Wait for GPIB RQS Function

Waits for the device indicated by address string to assert RQS.

Use the GPIB Wait function to wait for a specified device to assert any state.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• timeout ms (488.2 global) —

timeout ms specifies the time, in milliseconds, that the function waits before timing out.

The operation aborts if it does not complete within timeout ms. To disable timeouts, set
timeout ms to 0.

© National Instruments 2789

 Functions

To use the 488.2 global timeout, leave timeout ms unwired or set the input to –1. Then use the
SetTimeOut function to change the default value of timeout ms. The default is 10000.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• poll response byte —

poll response byte returns the serial poll response from the specified device. If SRQI is set, the
function polls the device at the specified address to see if the device requested service.

When the specified device requests service (the RQS bit—bit 6 in the device's Status Byte
Register—is TRUE), the function returns the serial poll response.

If the device indicated by address string does not respond within the timeout limit, poll
response byte is –1.

Note The bit definitions for the poll response byte vary among instruments.

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Trigger Function

Sends GET (Group Execute Trigger) to the device indicated by address string.

Inputs/Outputs
• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form

2790 ni.com
 Functions

primary+secondary. Both primary and secondary are decimal values, so if primary is 2

and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected

© National Instruments 2791

 Functions

Status Bit Numeric Value Symbolic Status Description

14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Clear Function

Sends either SDC (Selected Device Clear) or DCL (Device Clear).

Inputs/Outputs
• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• error in —

2792 ni.com
 Functions

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Serial Poll Function

Performs a serial poll of the device indicated by address string.

© National Instruments 2793

 Functions

Inputs/Outputs
• address string —

address string is the address of the device the function polls.

address string contains the address of the GPIB device with which the function communicates.
You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. If a controller ID is not present, the function defaults to controller (or bus) number
0.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• serial poll byte —

serial poll byte is the response from the device.

If the addressed device does not respond within the timeout limit, serial poll byte is -1.
• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2794 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Initialization Function

Configures the GPIB interface at address string.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• require re-addressing (T) —

If require re-addressing is TRUE, the function addresses the device before every read or write.

© National Instruments 2795

 Functions

If FALSE, the device must be able to retain addressing from one read or write to the next.
• assert REN with IFC (T) —

If assert REN with IFC is TRUE, and if this Controller (specified by the ID in address string) is the
System Controller, the function asserts the Remote Enable line.

• system controller (T) —

If system controller is TRUE, this Controller acts as the System Controller.

• address string —

address string sets the GPIB address of the GPIB controller itself.

The default value for address string is the configured address for the primary GPIB controller on
your system. The configured address is usually 0. You usually do not need to wire this input.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines which controller the function
uses. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• IST bit sense (T) —

If IST bit sense is TRUE, the Individual Status bit of the device responds TRUE to a parallel poll; if
IST bit sense is FALSE, the Individual Status bit of the device responds FALSE to a parallel poll.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• disallow DMA (F) —

If disallow DMA is TRUE, this device uses programmed I/O for data transfers.

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Status Function

Shows the present status of the GPIB Controller indicated by address string. Error I/O
operates uniquely in this function. The function gets the status of the GPIB Controller

2796 ni.com
 Functions

regardless of whether an error occurred in a preceding operation.

Inputs/Outputs
• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• error in —

error in describes error conditions that occur before this node runs. With the following
exception, this input provides standard error in functionality.

This node runs normally even if an error occurred before this node runs.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table

© National Instruments 2797

 Functions

also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• GPIB error —

GPIB error contains the most recent error code reported by any of the GPIB functions. Refer to
GPIB Error Codes for possible values for GPIB error if bit 15 of status is set.

• byte count —

byte count is the number of bytes the previous GPIB operation sent.

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Wait Function

Waits for the state(s) indicated by wait state vector at the device indicated by address
string.

Use the Wait for GPIB RQS function to wait for a device to assert RQS.

2798 ni.com
 Functions

Inputs/Outputs
• timeout ms (488.2 global) —

timeout ms specifies the time, in milliseconds, that the function waits before timing out.

The operation aborts if it does not complete within timeout ms. To enable timeouts, set bit 14 in
the wait state vector input. To disable timeouts, set timeout ms to 0.

To use the 488.2 global timeout, leave this input unwired. Then use the SetTimeOut function to
change the default value of timeout ms. The default is 10000.

• address string —

address string contains the address of the GPIB device with which the function communicates.

You can input both the primary and secondary addresses in address string by using the form
primary+secondary. Both primary and secondary are decimal values, so if primary is 2
and secondary is 3, address string is 2+3.

If you do not specify an address, the functions do not perform addressing before they attempt to
read and write the string. They assume you have either sent these commands another way or
that another controller is in charge and therefore responsible for the addressing. If the controller
is supposed to address the device but does not do so before the time limit expires, the functions
terminate with GPIB error 6 (timeout) and set bit 14 in status. If the GPIB is not the Controller-In-
Charge, do not specify address string.

When there are multiple GPIB controllers that LabVIEW can use, a prefix to address string in the
form ID:address (or ID: if no address is necessary) determines the controller that a specific
function uses. For example, to set GPIB controller 2 to talk to a device on address 3, use the
prefix 2:3. If a controller ID is not present, the function defaults to controller (or bus) number 0.

• wait state vector —

wait state vector indicates the states for which the function waits.

Each Boolean element in the array corresponds to a state that the device can wait on. If more
than one element is set to TRUE, the function terminates when any one of the states exists.

© National Instruments 2799

 Functions

The following table defines the states that you can specify in wait state vector. This table also
lists the numeric value and description of each element. While these elements are the same as
those that other GPIB functions return, only the states listed are valid for this function.

Wait State Vector Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the GPIB function sets bit 15. GPIB error is valid only if bit 15 of status is set.
Refer to the GPIB Status function for more information about status bits and GPIB error codes.

If you are waiting for multiple states, check status to see which state caused the function to
terminate.

This function can run in parallel with other functions because LabVIEW alternately checks for
status and executes other functions. In addition, multiple calls to this function can execute in
parallel, so you can wait for different states on different Controllers at the same time or for
multiple states to exist.

• error out —

error out contains error information. This output provides standard error out functionality.

2800 ni.com
 Functions

GPIB Misc Function

Performs the GPIB operation indicated by command string. Use this low-level function
when the other high-level, traditional GPIB functions are not suitable.

Inputs/Outputs
• command string —

command string is the GPIB operation to perform.

The following table shows the functions you can specify in command string.

Note address is the address in the command string.

Functions Type Description

cac 0/1 Controller Become active controller.
cmd string Controller Send IEEE 488 commands.
dma 0/1 Controller Set DMA mode or programmed I/O mode.
gts 0/1 Controller Go from active controller to standby.
ist 0/1 Controller Set individual status bit.
llo Controller Local lockout.
loc Controller Place controller in local state.
loc address Device Go to local.
off Controller Take controller offline.
off address Device Take device offline.
pct address Device Pass control.
ppc byte Controller Parallel poll configure (enable or disable).
ppc byte address Device Parallel poll configure (enable or disable).
ppu Controller Parallel poll unconfigure all devices.
rpp Controller Conduct parallel poll.
rsc 0/1 Controller Request or release system control.
rsv byte Controller Request service and/or set the serial poll status byte.
sic Controller Send interface clear and set remote enable (REN).

© National Instruments 2801

 Functions

Functions Type Description

sre 0/1 Controller Set or clear remote enable (REN).

To specify the GPIB Controller used by this function, use a command string in the form, ID: xxx,
where ID is the GPIB Controller (bus number) and xxx is the three-character command and its
corresponding arguments, if any. If you do not specify a Controller ID, LabVIEW assumes 0.

Refer to GPIB Device and Controller Functions for more information.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• output string —

output string is the response the function returns when you conduct a parallel poll with the rpp
command string. Set output string only when you use the rrp command string.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout

2802 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB 488.2

Use the GPIB 488.2 functions to exchange data and instructions between VIs and GPIB
488.2 devices.

The functions on this palette can return GPIB error codes.

Palette Object Description

Send Function Sends data bytes to a single GPIB device.
Receive
Reads data bytes from a GPIB device.
Function
Trigger
Triggers a single device.
Function
DevClear
Clears a single device.
Function
ReadStatus
Serial polls a single device to get its status byte.
Function
PPollConfig
Configures a device for parallel polls.
Function
Unconfigures devices for parallel polls. PPollUnconfig unconfigures the GPIB
PPollUnconfig
devices whose addresses are contained in the address list array for parallel polls.
Function
These devices no longer participate in polls.
PassControl
Passes control to another device with Controller capability.
Function

© National Instruments 2803

 Functions

Palette Object Description

SendList
Sends data bytes to multiple GPIB devices.
Function
FindRQS
Determines which device is requesting service.
Function
TriggerList
Triggers multiple devices simultaneously.
Function
DevClearList
Clears multiple devices simultaneously.
Function
AllSpoll
Serial polls all devices.
Function
PPoll Function Performs a parallel poll.
EnableRemote
Enables remote programming of multiple GPIB devices.
Function
EnableLocal
Enables local mode for multiple devices.
Function
FindLstn
Finds all Listeners on the GPIB.
Function
TestSys
Directs multiple devices to conduct IEEE 488.2 self-tests.
Function
ResetSys Performs bus initialization, message exchange initialization, and device
Function initialization.
SendIFC
Clears the GPIB functions with Interface Clear (IFC).
Function
TestSRQ
Determines the current state of the SRQ line.
Function
WaitSRQ
Waits until a device asserts Service Request.
Function
SetRWLS
Places particular devices in the Remote With Lockout State.
Function
SendLLO
Sends the Local Lockout (LLO) message to all devices.
Function
SendDataBytes
Sends data bytes to previously addressed devices.
Function

2804 ni.com
 Functions

Palette Object Description

SendSetup
Prepares particular devices to receive data bytes.
Function
SendCmds
Sends GPIB command bytes.
Function
RcvRespMsg
Reads data bytes from a previously addressed device.
Function
ReceiveSetup Prepares a device to send data bytes and prepares the GPIB controller to read data
Function bytes.
SetTimeOut
Changes the global timeout period for all GPIB 488.2 functions.
Function
Combines primary address and secondary address in a specially formatted
MakeAddr
packed address for devices that require both a primary and secondary GPIB
Function
address.

Send Function

Sends data bytes to a single GPIB device.

This function is similar to the SendList function, except that the Send function sends
data to a single GPIB device.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus The function addresses the interface indicated by bus as a Talker.

© National Instruments 2805

 Functions

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0. Refer to the software installation instructions included with your GPIB
controller for additional GPIB interfaces.

• address —

address addresses the device indicated by address as a Listener.

If you do not wire address, the function sends data string with no addressing, thereby sending it
to all previously addressed Listeners. To send data string to several devices, use the SendList
function. If a secondary address is required, use the MakeAddr function to format the primary
and secondary addresses properly.

• mode —

mode describes how to signal the end of the data to the Listener.

This input accepts the following values.

0 Do nothing to mark the end of the transfer (default).

1 Send NL (linefeed) with EOI after the data bytes.
2 Send EOI with the last data byte in the string.

• data string —

data string contains the data bytes that the function sends to the GPIB device.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2806 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

byte count refers to the number of bytes that pass over the GPIB.

• error out —

error out contains error information. This output provides standard error out functionality.

Receive Function

Reads data bytes from a GPIB device.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

© National Instruments 2807

 Functions

bus The function addresses the interface indicated by bus as a Listener.

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0. Refer to the software installation instructions included with your GPIB
controller for additional GPIB interfaces.
• address —

address contains the primary address of the GPIB device with which the function
communicates.

If a secondary address is required, use the MakeAddr function to format the primary and
secondary addresses.
• mode —

mode selects the method that signals the end of the data.

The default is 0. If mode is a value from decimal 0 through 255, the ASCII character that
corresponds to it is the termination character, and the function stops the read when it detects
the character. If mode is not wired, or is decimal 256, the function stops the read when it detects
END.
• count —

count is the maximum number of data bytes to return from the device in data string.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data string —

data string contains count data bytes from the GPIB device.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2808 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

byte count refers to the number of bytes that pass over the GPIB.

• error out —

error out contains error information. This output provides standard error out functionality.

Receive terminates when the function does one of the following:

• Reads the number of bytes requested

• Detects an error
• Exceeds the time limit
• Detects the END message (EOI asserted)
• Detects the EOS character (assuming the value supplied to mode has enabled this
option)

Trigger Function

Triggers a single device.

Use the TriggerList function to send a single message that triggers several GPIB
devices.

© National Instruments 2809

 Functions

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address —

address sends the GPIB Group Execute Trigger message to the device at address.

If the address terminal is not wired, the function sends the Group Execute Trigger message with
no addressing, and this triggers all previously addressed Listeners. If a secondary address is
required, use the MakeAddr function to put the primary and secondary addresses in the proper
format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active

2810 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

DevClear Function

Clears a single device.

Use the DevClearList function to send the Selected Device Clear (SDC) message to
several GPIB devices.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional

© National Instruments 2811

 Functions

GPIB interfaces.

• address —

address sends the GPIB SDC message to the device at address.

If the address terminal is not wired, the function sends the Universal Device Clear message to all
devices on the GPIB. If a secondary address is required, use the MakeAddr function to put the
primary and secondary addresses in the proper format.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

2812 ni.com
 Functions

ReadStatus Function

Serial polls a single device to get its status byte.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address —

address contains the primary address of the GPIB device with which the function
communicates.

If a secondary address is required, use the MakeAddr function to format the primary and
secondary addresses.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• serial poll response —

serial poll response is the status byte of the device at address.

Refer to the documentation supplied with the device to learn how to interpret this byte.
• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

© National Instruments 2813

 Functions

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

PPollConfig Function

Configures a device for parallel polls.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

2814 ni.com
 Functions

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address —

address configures the GPIB device at address for parallel polls according to the dataline and
sense parameters.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.
• dataline —

dataline is the data line, 1 to 8, on which the device responds to the parallel poll.

• sense —

sense indicates the condition under which the data line is asserted or unasserted.

The device compares the sense value, TRUE or FALSE, to its individual status bit and responds
accordingly.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted

© National Instruments 2815

 Functions

Status Bit Numeric Value Symbolic Status Description

5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

PPollUnconfig Function

Unconfigures devices for parallel polls. PPollUnconfig unconfigures the GPIB devices
whose addresses are contained in the address list array for parallel polls. These
devices no longer participate in polls.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

2816 ni.com
 Functions

address list contains a list of all of the instruments to which this function sends the Parallel Poll
Unconfigure command.

Each element of this array contains the primary address of a single instrument. If a secondary
address is required, use the MakeAddr function to format the primary and secondary addresses.
If you do not wire this input, this function sends the Parallel Poll Unconfigure command to all
connected GPIB instruments.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2817

 Functions

PassControl Function

Passes control to another device with Controller capability.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address —

address sends the GPIB Device Take Control message to the device specified by address.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2818 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

SendList Function

Sends data bytes to multiple GPIB devices.

This function is similar to the Send function, except that SendList sends data to
multiple listeners with only one transmission.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

© National Instruments 2819

 Functions

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.

• address list —

address list array contains a list of GPIB addresses for devices, which the function addresses as
Listeners.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.

• mode —

mode describes how to signal the end of the data to the Listener.

This input accepts the following values.

0 Do nothing to mark the end of the transfer (default).

1 Send NL (linefeed) with EOI after the data bytes.
2 Send EOI with the last data byte in the string.

• data string —

data string contains the data bytes that the function sends to the addressed devices.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2820 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

byte count refers to the number of bytes that pass over the GPIB.

• error out —

error out contains error information. This output provides standard error out functionality.

FindRQS Function

Determines which device is requesting service.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

© National Instruments 2821

 Functions

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list serial polls the GPIB devices listed in address list, starting at the beginning of the
address list array, until the function finds the device asserting SRQ.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• requester status byte —

requester status byte is the status byte for the device asserting SRQ.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected

2822 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• requester index —

requester index is the index of the address in address list of the device asserting SRQ.

• error out —

error out contains error information. This output provides standard error out functionality.

TriggerList Function

Triggers multiple devices simultaneously.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list simultaneously triggers GPIB devices whose addresses appear in address list.

If the address list terminal is not wired, the function sends the Group Execute Trigger message
without addressing, which triggers all previously addressed Listeners. If a secondary address is
required, use the MakeAddr function to put the primary and secondary addresses in the proper
format.

© National Instruments 2823

 Functions

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

DevClearList Function

Clears multiple devices simultaneously.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

2824 ni.com
 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.

• address list —

address list sends the GPIB Selected Device Clear (SDC) message to the devices listed in address
list.

If the address list terminal is not wired, the function sends the Universal Device Clear message
to all devices on the GPIB. If a secondary address is required, use the MakeAddr function to put
the primary and secondary addresses in the proper format.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted

© National Instruments 2825

 Functions

Status Bit Numeric Value Symbolic Status Description

5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

AllSpoll Function

Serial polls all devices.

Although the AllSpoll function is general enough to serial poll any number of GPIB
devices, use the ReadStatus function when you serial poll only one GPIB device.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.

2826 ni.com
 Functions

• address list —

address list serial polls GPIB devices whose addresses appear in address list.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• serial poll byte list —

serial poll byte list contains the responses of the devices whose addresses are contained in the
corresponding elements of address list.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit instatus. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

© National Instruments 2827

 Functions

byte count contains the index of any device that times out instead of responding to the poll.

On success, byte count returns the number of responses in serial poll byte list. If an error
occurs, byte count returns the index of address list of the first address that timed out or was
invalid.

• error out —

error out contains error information. This output provides standard error out functionality.

PPoll Function

Performs a parallel poll.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• parallel poll byte —

parallel poll byte is the result of the parallel poll.

Each bit of the poll result returns one bit of status information from each device configured for
parallel polls. The state of each bit, 0 or 1, and the interpretation of these states are based on the

2828 ni.com
 Functions

latest parallel poll configuration sent to the devices and on the individual status of the devices.
• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

EnableRemote Function

Enables remote programming of multiple GPIB devices.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

© National Instruments 2829

 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list sends the GPIB Remote Enable (REN) command to the devices listed in address list.

If the address list terminal is not wired, the function performs no addressing, and the Remote
Enable (REN) line asserts. If a secondary address is required, use the MakeAddr function to put
the primary and secondary addresses in the proper format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected

2830 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

EnableLocal Function

Enables local mode for multiple devices.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list sends the GPIB Go To Local (GTL) command to the devices listed in address list.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

© National Instruments 2831

 Functions

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

FindLstn Function

Finds all Listeners on the GPIB.

FindLstn detects the presence of devices at particular addresses because most GPIB
devices have the ability to listen. When you detect the devices, you can usually
interrogate them to determine their identity.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

2832 ni.com
 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list tests for the presence of a Listener for all devices listed in address list.

If the function does not detect a listening device at the particular primary address, it tests all the
secondary addresses associated with that primary address.
• limit —

limit If more Listeners are present on the bus than limit specifies, the function truncates listener
address list after limit entries.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• listener address list —

listener address list contains the addresses of all the Listeners the function finds.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

© National Instruments 2833

 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• number of listeners —

number of listeners contains the number of addresses placed in listener address list.

• error out —

error out contains error information. This output provides standard error out functionality.

TestSys Function

Directs multiple devices to conduct IEEE 488.2 self-tests.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

2834 ni.com
 Functions

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list contains a list of GPIB devices which receive instructions from the function to
conduct their self-test procedures.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• result list —

result list Each device returns an integer code signifying the results of its tests. TestSys returns
these codes in the corresponding elements of result list.

A result code of 0 indicates the device passed its tests. Any other value indicates the tests
resulted in an error.
• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State

© National Instruments 2835

 Functions

Status Bit Numeric Value Symbolic Status Description

8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• failed devices —

failed devices contains the number of devices that failed their tests.

• error out —

error out contains error information. This output provides standard error out functionality.

ResetSys Function

Performs bus initialization, message exchange initialization, and device initialization.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list contains the primary address of the GPIB device with which the function
communicates.

2836 ni.com
 Functions

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

First, the function asserts Remote Enable (REN), followed by Interface Clear (IFC),
unaddressing all devices and making the GPIB controller (the System Controller) the
Controller-In-Charge.

Second, the function sends the Device Clear (DCL) message to all connected devices.
This ensures that all IEEE 488.2-compatible devices can receive the Reset (RST)

© National Instruments 2837

 Functions

message that follows.

Third, the function sends the *RST message to all devices whose addresses are
contained in the address list array. This message initializes device-specific functions
within each device.

SendIFC Function

Clears the GPIB functions with Interface Clear (IFC).

When you issue the GPIB Device IFC message, the interface functions of all connected
devices return to their cleared states.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2838 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

Use this function as part of a GPIB initialization. It forces the interface to be Controller
of the GPIB and ensures that the connected devices are all unaddressed and that the
interface functions of the devices are in their idle states.

TestSRQ Function

Determines the current state of the SRQ line.

This function is similar in format to the WaitSRQ function, except that WaitSRQ
suspends itself while it waits for an occurrence of SRQ, and TestSRQ immediately
returns the current SRQ state.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

© National Instruments 2839

 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• SRQ —

SRQ is TRUE if the SRQ line is asserted and FALSE if it is not.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

2840 ni.com
 Functions

error out contains error information. This output provides standard error out functionality.

WaitSRQ Function

Waits until a device asserts Service Request.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• SRQ —

If the SRQ occurs within the timeout period specified in the GPIB configuration, the function
returns TRUE in SRQ.

Otherwise, the function returns FALSE.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

© National Instruments 2841

 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

The function suspends execution until a GPIB device connected on the GPIB asserts
the Service Request (SRQ) line.

WaitSRQ is similar in format to the TestSRQ function, except that TestSRQ returns the
SRQ status immediately, whereas WaitSRQ suspends the program for the duration of
the timeout period, but no longer, waiting for an SRQ to occur.

SetRWLS Function

Places particular devices in the Remote With Lockout State.

Inputs/Outputs
• bus —

2842 ni.com
 Functions

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list contains a list of the GPIB devices with which the function communicates.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

© National Instruments 2843

 Functions

The function sends Remote Enable (REN) to the GPIB devices listed in address list. It
also places all devices in Lockout State, which prevents them from independently
returning to local programming mode without intervention by the Controller.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

SendLLO Function

Sends the Local Lockout (LLO) message to all devices.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2844 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

When the function sends the GPIB Local Lockout message, a device cannot
independently choose the local or remote state. While Local Lockout is in effect, only
the Controller can alter the local or remote state of the devices by sending the
appropriate GPIB messages. Use SendLLO only in unusual local/remote situations,
particularly those in which you must lock all devices into local programming state. Use
the SetRWLS function when you want to place devices in Remote Mode With Lockout
State.

SendDataBytes Function

Sends data bytes to previously addressed devices.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

© National Instruments 2845

 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.

• mode —

mode describes how to signal the end of the data to the Listener.

This input accepts the following values.

0 Do nothing to mark the end of the transfer (default).

1 Send NL (linefeed) with EOI after the data bytes.
2 Send EOI with the last data byte in the string.

• data string —

data string contains the data bytes the function sends over the GPIB.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

2846 ni.com
 Functions

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

byte count refers to the number of bytes that pass over the GPIB.

• error out —

error out contains error information. This output provides standard error out functionality.

SendSetup Function

Prepares particular devices to receive data bytes.

You normally follow a call to this function with a call to a function such as
SendDataBytes to actually transfer the data to the Listeners. This sequence eliminates
the need to readdress the devices between blocks of sends.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

© National Instruments 2847

 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address list —

address list addresses GPIB devices whose addresses appear in address list as Listeners.

If a secondary address is required, use the MakeAddr function to put the primary and secondary
addresses in the proper format.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

2848 ni.com
 Functions

• error out —

error out contains error information. This output provides standard error out functionality.

SendCmds Function

Sends GPIB command bytes.

You normally do not need to use SendCmds for GPIB operation. Use it when
specialized command sequences, not provided for in other functions, must be sent
over the GPIB.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Refer to GPIB Multiline Interface Messages for more information about available
commands.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• command string —

command string contains the command bytes the function sends over the GPIB.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

© National Instruments 2849

 Functions

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

byte count refers to the number of bytes that pass over the GPIB.

• error out —

error out contains error information. This output provides standard error out functionality.

RcvRespMsg Function

Reads data bytes from a previously addressed device.

RcvRespMsg assumes that another function, such as ReceiveSetup, Receive, or

SendCmds, has already addressed the GPIB Talkers and Listeners. You use RcvRespMsg
specifically to skip the addressing step of GPIB management. Use the Receive function
to perform the entire sequence of addressing and then to receive the data bytes.

2850 ni.com
 Functions

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• mode —

mode determines the data termination method.

The default is 0. If mode is from 0 through decimal 255, the ASCII character that corresponds to it
is the termination character, and the function stops the read when it detects the character. If
mode is not wired or is decimal 256, the read stops when the function detects the END message
(EOI).
• count —

count is the maximum number of data bytes to read from the GPIB.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• data string —

data string contains the bytes read from the GPIB.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

© National Instruments 2851

 Functions

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State
7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• byte count —

byte count refers to the number of bytes that pass over the GPIB.

• error out —

error out contains error information. This output provides standard error out functionality.

ReceiveSetup Function

Prepares a device to send data bytes and prepares the GPIB controller to read data
bytes.

After you call this function, you can use a function such as RcvRespMsg to transfer the
data from the Talker. In this way, you eliminate the need to readdress the devices
between blocks of reads.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

2852 ni.com
 Functions

Inputs/Outputs
• bus —

bus refers to the GPIB bus number. If you have only one GPIB interface in your computer, the
default bus number is 0.

Refer to the software installation instructions included with the GPIB controller for additional
GPIB interfaces.
• address —

address prepares a device to send data bytes by addressing the device as a Talker and prepares
the GPIB controller to receive transmitted data bytes.

address contains the primary address of the GPIB device with which the function
communicates. If a secondary address is required, use the MakeAddr function to format the
primary and secondary addresses.
• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• status —

status is a Boolean array in which each bit describes a state of the GPIB Controller.

If an error occurs, the function sets bit 15. GPIB error is valid only if bit 15 of status is set.

The following table shows the numeric value and symbolic status of each bit in status. This table
also includes a description of each bit.

Status Bit Numeric Value Symbolic Status Description

0 1 DCAS Device Clear state
1 2 DTAS Device Trigger State
2 4 LACS Listener Active
3 8 TACS Talker Active
4 16 ATN Attention Asserted
5 32 CIC Controller-In-Charge
6 64 REM Remote State

© National Instruments 2853

 Functions

Status Bit Numeric Value Symbolic Status Description

7 128 LOK Lockout State
8 256 CMPL Operation Completed
12 4096 SRQI SRQ Detected while CIC
13 8192 END EOI or EOS Detected
14 16384 TIMO Timeout
15 -32768 ERR Error Detected

• error out —

error out contains error information. This output provides standard error out functionality.

SetTimeOut Function

Changes the global timeout period for all GPIB 488.2 functions.

This function also sets the default timeout period for all GPIB functions. This function
defaults to the next higher ibtmo value.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• new timeout (10000) —

new timeout defaults to 10,000 ms.

• previous timeout —

previous timeout is the previous timeout period for all GPIB 488.2 functions.

The following table lists some sample input values and their resulting timeout values.

2854 ni.com
 Functions

Input Value Resulting Timeout

0-1ms 1ms
1ms 3ms
4-10ms 10ms
11-30ms 30ms
31-100ms 100ms
101-300ms 300ms
301-1000ms 1s
1001-3000ms 3s
3001-10000ms 10s
10001-30000ms 30s
30001-100000ms 100s
100001-300000ms 300s
300001+ ms 1000s

MakeAddr Function

Combines primary address and secondary address in a specially formatted packed

address for devices that require both a primary and secondary GPIB address.

Refer to GPIB Function Defaults for more information about the timeout and address
defaults.

Inputs/Outputs
• primary address —

primary address is placed in the lower byte of the packed address by MakeAddr.

• secondary address —

© National Instruments 2855

 Functions

secondary address is placed in the upper byte of the packed address by MakeAddr.

• error in —

error in describes error conditions that occur before this node runs. This input provides
standard error in functionality.

• packed address —

packed address contains primary address in its lower byte and secondary address in its upper
byte. You can use packed address as the address input to the GPIB 488.2 Functions.

• error out —

error out contains error information. This output provides standard error out functionality.

GPIB Device and Controller Functions

The GPIB Device and Controller functions listed in the GPIB Misc function description
are described here. Notice that there are both device and controller versions of the ppc
and loc commands. The syntax and use of the commands are slightly different for each
version.

You can use these functions with all GPIB Controllers accessible by LabVIEW unless
stated otherwise in the function description. An ECMD error (17) results when you
execute a function for a GPIB Controller without the specified capability. The function
syntax is strict. Each function recognizes only lowercase characters and allows only
one space between the function name and the arguments.

Controller Functions

The controller functions configure the controller or send IEEE 488 commands to which
all instruments respond.

cac—Become Active Controller

cmd—Send IEEE 488 Commands

2856 ni.com
 Functions

dma—Set DMA Mode or Programmed I/O Mode

gts—Go from Active Controller to Standby

ist—Set Individual Status Bit

llo—Local Lockout

loc—Place Controller in Local State

off—Take Controller Offline

ppc—Parallel Poll Configure (Enable and Disable)

ppu—Parallel Poll Unconfigure

rpp—Conduct Parallel Poll

rsc—Release or Request System Control

rsv—Request Service and/or Set the Serial Poll Status Byte

sic—Send Interface Clear

sre—Unassert or Assert Remote Enable

cac—Become Active Controller

syntax cac 0 (take control synchronously)

cac 1 (take control immediately)

cac takes control either synchronously or immediately, and in some cases

asynchronously. You generally do not need to use the cac function because other
functions, such as cmd and rpp, take control automatically.

If you try to take control synchronously when a data handshake is in progress, the
function postpones the take control action until the handshake is complete. If a
handshake is not in progress, the function executes the take control action

© National Instruments 2857

 Functions

immediately. Taking control synchronously is not guaranteed if a read or write

operation completes with a timeout or other error.

You should take control asynchronously when it is impossible to gain control

synchronously, for example, after a timeout error.

The ECIC error results if the GPIB controller is not CIC.

cmd—Send IEEE 488 Commands

syntax cmd string

cmd sends GPIB command messages. These command messages include device talk
and listen addresses, secondary addresses, serial and parallel poll configuration
messages, and device clear and trigger messages.

You do not use cmd to transmit programming instructions to devices. The GPIB Read
and GPIB Write functions transmit programming instructions and other device-
dependent information.

string contains the command bytes the controller sends. ASCII characters represent
these bytes in cmd string. If you must send characters that cannot be displayed, you
can enable backslash codes on the string control or string constant, or you can use a
format function to list the commands in hexadecimal.

dma—Set DMA Mode or Programmed I/O Mode

syntax dma 0 (use programmed I/O)

dma 1 (use DMA)

dma indicates whether data transfers use DMA.

Some GPIB controllers do not have DMA capability. If you try to execute dma 1, the
function returns GPIB error 11 to indicate no capability.

2858 ni.com
 Functions

gts—Go from Active Controller to Standby

syntax gts 0 (no shadow handshaking)

gts 1 (shadow handshaking)

gts sets the GPIB controller to the controller standby state and unasserts the ATN
signal if it is the active controller. Normally, the GPIB controller is involved in the data
transfer. gts permits GPIB devices to transfer data without involving the GPIB
controller.

If shadow handshaking is active, the GPIB controller participates in the GPIB transfer
as a listener but does not accept any data. When it detects the END message, the GPIB
controller asserts the Not Ready For Data (NRFD) to create a handshake holdoff state.

If shadow handshaking is not active, the GPIB controller performs neither shadow
handshaking nor a handshake holdoff.

If you enable the shadow handshake option, the GPIB controller participates in a data
handshake as a listener without actually reading the data. It monitors the transfer for
the END message and stops subsequent transfers. This mechanism allows the GPIB
controller to take control synchronously on subsequent operations such as cmd or
rpp.

After you send the gts command, wait for END before you initiate another GPIB
command. You can do this with the GPIB Wait function.

The ECIC error results if the GPIB controller is not CIC.

ist—Set Individual Status Bit

syntax ist 0 (individual status bit is cleared)

ist 1 (individual status bit is set)
ist sets the sense of the individual status (ist) bit.

Use ist when the GPIB controller is not the CIC but participates in a parallel poll
conducted by a device that is the active controller. The CIC conducts a parallel poll by

© National Instruments 2859

 Functions

asserting the EOI and ATN signals, which send the Identify (IDY) message. While this
message is active, each device that you configured to participate in the poll responds
by asserting a predetermined GPIB data line either TRUE or FALSE, depending on the
value of its local ist bit. For example, you can assign the GPIB controller to drive the
DIO3 data line TRUE if ist is 1 and FALSE if ist is 0. Conversely, you can assign it to drive
DIO3 TRUE if ist is 0 and FALSE if ist is 1.

The Parallel Poll Enable (PPE) message in effect for each device determines the
relationship among the value of ist, the line that is driven, and the sense at which the
line is driven. The GPIB controller is capable of receiving this message either locally
using ppc or remotely through a command from the CIC. After the PPE message
executes, ist changes the sense at which the GPIB controller drives the line during the
parallel poll, and the GPIB controller can convey a one-bit, device-dependent message
to the controller.

llo—Local Lockout

syntax llo

llo places all devices in local lockout state. This action usually inhibits recognition of
inputs from the front panel of the device.

llo sends the Local Lockout (LLO) command.

loc—Place Controller in Local State

syntax loc

loc places the GPIB controller in a local state by sending the local message Return To
Local (RTL) if it is not locked in remote mode (indicated by the LOK bit of status). You
use loc to simulate a front panel RTL switch when you use a computer to simulate an
instrument.

off—Take Controller Offline

syntax off

2860 ni.com
 Functions

off takes the controller offline. This is only needed when sharing the controller with
another application which is using the NI-488 Library.

ppc—Parallel Poll Configure (Enable and Disable)

syntax ppc byte

ppc configures the GPIB Controller to participate in a parallel poll by setting its Local
Poll Enable (LPE) message to the value of byte. If the value of byte is 0, the GPIB
controller unconfigures itself.

Each of the 16 Parallel Poll Enable (PPE) messages selects the GPIB data line (DIO1
through DIO8) and sense (1 or 0) that the device must use when responding to the
Identify (IDY) message during a parallel poll. The device interprets the assigned
message and the current value of the individual status (ist) bit to determine if the
selected line is driven TRUE or FALSE. For example, if PPE=0x64, DIO5 is driven TRUE if
ist is 0 and FALSE if ist is 1. If PPE=0x68, DIO1 PPE message is in effect. You must know
which PPE and PPD messages are sent and determine what the responses indicate.

ppu—Parallel Poll Unconfigure

syntax ppu

ppu disables all devices from responding to parallel polls.

ppu sends the Parallel Poll Unconfigure (PPU) command.

rpp—Conduct Parallel Poll

syntax rpp

rpp conducts a parallel poll of previously configured devices by asserting the ATN and
EOI signals, which sends the IDY message.

rpp places the parallel poll response in the output string as ASCII characters.

© National Instruments 2861

 Functions

rsc—Release or Request System Control

syntax rsc 0 (release system control)

rsc 1 (request system control)

rsc releases or requests the capability of the GPIB controller to send the Interface Clear
(IFC) and Remote Enable (REN) messages to GPIB devices using the sic and sre
functions. For the GPIB controller to respond to IFC sent by another controller, the
GPIB controller must not be the system controller.

In most applications, the GPIB controller is always the system controller. You use rsc
only if the computer is not the system controller for the duration of the program
execution.

rsv—Request Service and/or Set the Serial Poll Status Byte

syntax rsv byte

rsv sets the serial poll status byte of the GPIB controller to byte. If the 0x40 bit is set in
byte, the GPIB controller also requests service from the controller by asserting the
GPIB RQS line. For example, if you want to assert the GPIB RQS line, send the ASCII
character @, in which the 0x40 bit is set.

You use rsv to request service from the controller using the Service Request (SRQ)
signal and to provide a system-dependent status byte when the controller serial polls
the GPIB port.

sic—Send Interface Clear

syntax sic

sic causes the controller to assert the IFC signal for at least 100 ms if the controller has
system controller authority. This action initializes the GPIB and makes the Controller
port CIC. You generally use sic when you want a device to become CIC or to clear a bus
fault condition.

2862 ni.com
 Functions

The IFC signal resets only the GPIB functions of bus devices; it does not reset internal
device functions. The Device Clear (DCL) and Selected Device Clear (SDC) commands
reset the device functions. Consult the instrument documentation to determine the
effect of these messages.

sre—Unassert or Assert Remote Enable

syntax sre 0 (unassert Remote Enable)

sre 1 (assert Remote Enable)

sre unasserts or asserts the GPIB REN line. Devices monitor REN when they select
between local and remote modes of operation. A device does not actually enter
remote mode until it receives its listen address.

The ESAC error occurs if the controller is not system controller.

Device Functions

The device functions send configuration information to a specific instrument or device.

loc—Go to local

off—Take device offline

pct—Pass control

ppc—Parallel poll configure

loc—Go to local

syntax loc address

loc temporarily moves devices from a remote program mode to a local mode.

address is the GPIB address of the device. This argument indicates both primary and
secondary addresses if you use the form primary+secondary, where primary and
secondary are the decimal values of the primary and secondary addresses. For

© National Instruments 2863

 Functions

example, if primary is 2 and secondary is 3, address is 2+3.

loc sends the GTL (Go To Local) message to the GPIB device.

off—Take device offline

syntax off address

off takes the device at the specified GPIB address offline. This is only needed when
sharing a device with another application which is using the NI-488 GPIB Library.

address is the GPIB address of the device. This argument indicates both primary and
secondary addresses if you use the form primary+secondary, where primary and
secondary are the decimal values of the primary and secondary addresses. For
example, if primary is 2 and secondary is 3, address is 2+3.

pct—Pass control

syntax pct address

pct passes Controller-In-Charge (CIC) authority to the device at the specified address.
The GPIB Controller becomes idle automatically. The function assumes that the device
to which pct passes control has Controller capability.

address is the GPIB address of the device. This argument indicates both primary and
secondary addresses if you use the form primary+secondary, where primary and
secondary are the decimal values of the primary and secondary addresses. For
example, if primary is 2 and secondary is 3, address is 2+3.

pct sends the following command sequence:

1. Talk address of the device

2. Secondary address of the device, if applicable
3. Take Control (TCT)

2864 ni.com
 Functions

ppc—Parallel poll configure

syntax ppc byte address

ppc enables the instrument to respond to parallel polls.

byte is 0 or a valid parallel poll enable (PPE) command. If byte is 0, the parallel poll
disable (PPD) byte 0x70 is sent to disable the device from responding to a parallel poll.
Each of the 16 PPE messages selects a GPIB data line (DIO1 through DIO8) and sense (1
or 0) that the device must use when it responds to the Identify (IDY) message during a
parallel poll. The device compares the ist sense and drives the indicated DIO line TRUE
or FALSE.

address is the GPIB address of the device. This argument indicates both primary and
secondary addresses if you use the form primary+secondary, where primary and
secondary are the decimal values of the primary and secondary addresses. For
example, if primary is 2 and secondary is 3, address is 2+3.

GPIB Function Defaults

When using GPIB functions, the default primary address of the GPIB controller is 0,
with no secondary address. It is designated as System Controller. The default timeout
value for GPIB functions is 10 seconds. If you want to set the primary address or
change the default timeout value, use the configuration utility included with the GPIB
controller.

You also can use the GPIB Initialization and SetTimeOut functions to set the primary
address and to change the default timeout value at run time, but these functions affect
the interface only when you use it with LabVIEW. Refer to the documentation supplied
with the hardware interface for more information.

GPIB Multiline Interface Messages

Multiline Interface Messages are commands that IEEE 488 defines. Multiline interface
messages manage GPIB by performing tasks such as initializing the bus, addressing
and unaddressing devices, and setting device modes for local or remote programming.
These multiline interface messages are sent and received with ATN TRUE.

© National Instruments 2865

 Functions

The GPIB Multiline Interface Messages can return the following message codes.

Mnemonic Definition
DCL Device Clear
GET Group Execute Trigger
GTL Go To Local
LLO Local Lockout
MLA My Listen Address
MSA My Secondary Address
MTA My Talk Address
PPC Parallel Poll Configure
PPD Parallel Poll Disable
PPE Parallel Poll Enable
PPU Parallel Poll Unconfigure
SDC Selected Device Clear
SPD Serial Poll Disable
SPE Serial Poll Enable
TCT Take Control
UNL Unlisten
UNT Untalk

Refer to the ANSI/IEEE Standard 488.1-1987, IEEE Standard Digital Interface for
Programmable Instrumentation, for more information about these messages.

Refer to ASCII Codes for a list of ASCII codes.

Configuring Serial and Parallel Ports with VISA

NI-VISA automatically detects ports. You can view the list of ports with a VISA resource
name control on the front panel or with the VISA Find Resource function. The
maximum number of serial ports that NI-VISA supports on any platform is 256. The

2866 ni.com
 Functions

default numbering of serial ports is system dependent.

(Windows) NI-VISA supports interaction with parallel ports as well as with serial ports
on your computer. You can use the VISA properties to communicate with parallel ports
in the same way you communicate with serial ports.

Note You may receive unexpected errors while attempting to write to a

parallel port if you leave floating pins. Unlike the serial ports, parallel ports
have pins that, if left floating, cause the port driver to assume that the
attached device is busy (pin 11) or out of paper (pin 12). Ground pins 11 and
12 on the port to ensure that you can write successfully to the port.

VISA Resource Name Control

Use the VISA resource name control to specify the resource to which a VISA session
will be opened and to maintain the session and class. A VISA session is a unique logical
identifier used by VISA to communicate with a resource. The VISA session is
maintained by the VISA resource name control and is not seen by the user. VISA
resource name out is a copy of the resource name that is passed out of the VISA
functions. By passing the resource name in and out of functions and VIs, you can
simplify dataflow programming by chaining functions and VIs together. This is similar
to the file refnum outputs used by the File I/O functions.

The following table shows the syntax for the VISA resource name string. Optional
parameters are shown in square brackets ([ ]).

Interface Syntax Classes

Instr;

VXI/GPIB-VXI MBD
VXI INSTR VXI[board]::VXI logical address[::INSTR] Instr;

VXI/GPIB-VXI/VME
RBD Instr

VXI MEMACC VXI[board]::MEMACC VXI/GPIB-VXI/VME

© National Instruments 2867

 Functions

Interface Syntax Classes

MemAcc
VXI VXI/GPIB-VXI
VXI[board][::VXI logical address]::BACKPLANE
BACKPLANE Backplane
VXI SERVANT VXI[board]::SERVANT VXI Servant

VXI/GPIB-VXI MBD
Instr;
GPIB-VXI
GPIB-VXI[board]::VXI logical address[::INSTR]
INSTR
VXI/GPIB-VXI/VME
RBD Instr

GPIB-VXI VXI/GPIB-VXI/VME
GPIB-VXI[board]::MEMACC
MEMACC MemAcc
GPIB-VXI VXI/GPIB-VXI
GPIB-VXI[board][::VXI logical address]::BACKPLANE
BACKPLANE Backplane
GPIB[board]::primary address[::GPIB secondary
GPIB INSTR GPIB Instr
address][::INSTR]
GPIB
GPIB INTFC GPIB[board]::INTFC
BoardInterface
GPIB
GPIB[board]::SERVANT N/A
SERVANT
PXI INSTR PXI[bus]::device[::function][::INSTR] PXI Instr
PXI INSTR PXI[interface]::[bus-]device[.function][::INSTR] PXI Instr
PXI MEMACC PXI[interface]::MEMACC PXI MemAcc
Serial INSTR ASRL[board][::INSTR] Serial Instr
TCPIP INSTR TCPIP[board]::host address[::LAN device name][::INSTR] TCP/IP Instr
TCPIP
TCPIP[board]::host address::port::SOCKET TCP/IP Socket
SOCKET
USB[board]::manufacturer ID::model code::serial
USB INSTR USB Instr
number[::USB interface number][::INSTR]
USB[board]::manufacturer ID::model code::serial
USB RAW USB Raw
number[::USB interface number]::RAW

2868 ni.com
 Functions

The VXI keyword is used for VXI instruments through either embedded or MXIbus
controllers. The GPIB keyword is used to establish communication with a GPIB device.
The GPIB-VXI keyword is used for a GPIB-VXI controller. The ASRL keyword is used to
establish communication with an asynchronous serial (such as RS232) device.

The INSTR keyword specifies a VISA resource of the type INSTR.

The following table shows the default value for optional string segments.

Optional String Segment Default Value

board 0
GPIB secondary address None
LAN device name inst0
PXI function 0
USB interface number lowest numbered relevant interface

The following table shows examples of address strings.

Address String Description

VXI0::1::INSTR A VXI device at logical address 1 in VXI interface VXI0.
A VXI device at logical address 9 in a GPIB-VXI controlled
GPIB-VXI::9::INSTR
system.
A GPIB device at primary address 1 and secondary address 0 in
GPIB::1::0::INSTR
GPIB interface 0.
ASRL1::INSTR A serial device attached to interface ASRL1.
VXI::MEMACC Board-level register access to the VXI interface.
GPIB-VXI1::MEMACC Board-level register access to GPIB-VXI interface number 1.
GPIB2::INTFC Interface or raw resource for GPIB interface 2.
Mainframe resource for chassis 1 on the default VXI system,
VXI::1::BACKPLANE
which is interface 0.
GPIB-VXI2::BACKPLANE Mainframe resource for default chassis on GPIB-VXI interface 2.
GPIB1::SERVANT Servant/device-side resource for GPIB interface 1.

© National Instruments 2869

 Functions

Address String Description

VXI0::SERVANT Servant/device-side resource for VXI interface 0.
TCPIP0::1.2.3.4::999::SOCKET Raw TCP/IP access to port 999 at the specified IP address.
A TCP/IP device using VXI-11 located at the specified address.
TCPIP::dev.company.com::INSTR
This uses the default LAN Device Name of inst0.
PXI::15::INSTR PXI device number 15 on bus 0.
PXI0::2-12.1::INSTR PXI bus number 2, device 12 with function 1.
PXI0::MEMACC PXI MEMACC session.
The resource on the specified remote system. The hostname
can be represented as either an IP address (dot-notation) or
visa://hostname/resource
network machine name. This remote system need not be
explicitly configured on the client system.
A USB Test & Measurement class device with manufacturer ID
0x1234, model code 125, and serial number A22-5. This uses the
USB::0x1234::125::A22-5::INSTR
first available USBTMC interface of the device. This is usually
number 0.
A raw USB nonclass device with manufacturer ID 0x5678, model
USB::0x5678::0x33::SN999::1::RAW code 0x33, and serial number SN999. This uses the device
interface number 1.

By default, the VISA resource name control is set to the Instr class, which also
corresponds to the class of the session to be opened. You can change the class type by
right-clicking the control in edit mode and selecting a different class from the shortcut
menu.

VISA functions vary in the class of VISA resource name that can be wired to them. The
valid classes for each function are listed in the NI-VISA Help. For example, the functions
on the Register Access and Low Level Register Access palettes do not accept VISA
sessions of class GPIB Instr or Serial Instr.

If you wire the VISA resource name control to a function that does not accept the class
of the session, or if you wire two resource names of differing classes together, the
block diagram will not run and a Class Conflict error is reported.

2870 ni.com
 Functions

Note You can wire resource names set to the Event classes only to the VISA
Close function and a Property Node.

If you wire the VISA resource name control to a function that does not accept the class
of the session, or if you wire two resource names of differing classes together, the
block diagram will not run and a Class Conflict error is reported.

Note VISA name controls and constants are available on all platforms.
However, if you try to run a VI with a name control that contains a resource
string for a device that your platform does not support, you will receive an
error.

VISA Events
The VIs and functions on the Event Handling palette handle VISA events. To handle
VISA events, you must enable event queuing with the VISA Enable Event function.
Queues work per session and per event type, so you must enable queuing on every
session for which you want to handle events.

Use the VISA Wait on Event function to retrieve events from a queue. If an event of the
specified type already has occurred, calling VISA Wait on Event returns that event
immediately, regardless of the value you set for the timeout parameter.

You also can use VISA Wait on Event to wait for events that currently do not exist in the
queue. Execution stops until an event of the specified type arrives or until the VISA
Wait on Event function times out. Set a reasonable timeout value to wait for events
that currently do not exist in the queue.

Tip To check if the queue contains any events of the type you specified, set
timeout on the VISA Wait on Event function to 0 (immediate).

When the VISA Wait on Event function returns an event, the event no longer exists in
the queue for the session on which you invoked the wait operation. However, if event
queuing is enabled on any other VISA session, the event remains in the queue for that
session until it is retrieved.

© National Instruments 2871

 Functions

Use the VISA Disable Event function to disable event queuing on a specific VISA
session. When you call this function, no additional events are added to the queue for
the session. However, the queue retains any events that already existed in the queue.
You can either retrieve or discard these events. To retrieve the events, use the VISA
Wait on Event function. To discard the events, use the VISA Discard Events function.

The default length of VISA event queues is 50. If the queue is full and a new event
arrives, the new event is discarded. Event queues in VISA do not grow dynamically, but
you can use the General Settings:Maximum Queue Length property to change the size
of an event queue programmatically. If you change the queue length on a given
session, you must do so before VISA Enable Event is called for the first time.

The following table lists the events you can handle with these VIs and functions. This
table includes a description of each event along with its supported resource classes,
such as GPIB, PXI etc.

Note The serial events are valid only on Windows and platforms on which
National Instruments supports its ENET-Serial products.

Event Resource
Description
Name Classes

Notifies the application that a service request was received from the GPIB INSTR,
device or interface associated with the given session. GPIB INTFC,
GPIB-VXI
Service
INSTR, TCPIP
Request Note When you receive this event on an instrument session, INSTR, USB
you must call VISA Read STB to guarantee delivery of future INSTR, VXI
service request events on the given session. INSTR

GPIB INTFC,
Notifies the application that a trigger interrupt was received from the
VXI INSTR, VXI
Trigger device. This may be either a hardware or software trigger, depending on
BACKPLANE,
the interface and the current session settings.
VXI SERVANT
Notifies the application that a device clear message was sent to the GPIB INTFC,
Clear
local controller. VXI SERVANT
Notifies the application that a VXIbus signal or VXIbus interrupt was
VXI Signal VXI INSTR
received from the device associated with the given session.

2872 ni.com
 Functions

Event Resource
Description
Name Classes
VXI/VME Notifies the application that a VXIbus interrupt was received from the
VXI INSTR
Interrupt device associated with the given session.
VXI/VME VXI
Notifies the application that the VXI/VME SYSFAIL* line was asserted.
Sysfail BACKPLANE
VXI
VXI/VME
Notifies the application that the VXI/VME SYSRESET* line was asserted. BACKPLANE,
Sysreset
VXI SERVANT
Notifies the application that the GPIB controller has gained or lost CIC
GPIB CIC GPIB INTFC
(controller-in-charge) status.
GPIB Talk Notifies the application that the GPIB controller was addressed to talk. GPIB INTFC
GPIB Notifies the application that the GPIB controller has been addressed to
GPIB INTFC
Listen listen.
PXI
Notifies the application that a PXI interrupt occurred. PXI INSTR
Interrupt
USB USB INSTR,
Notifies the application that a USB interrupt has occurred.
Interrupt USB RAW
Serial
Notifies the application that a break signal was received. Serial INSTR
Break
Notifies the application that the termination character was received.
The actual termination character is specified by setting the Message
Serial
Based Settings:Termination Character Enable property prior to enabling Serial INSTR
TermChar
this event. For this event, the setting of the Message Based
Settings:Termination Character Enable property is ignored.
Notifies the application that the Clear To Send (CTS) line changed state.
Serial
If the CTS line changes state quickly several times in succession, not all Serial INSTR
CTS
line state changes necessarily result in event notifications.
Notifies the applications that the Data Set Ready (DSR) line changed
Serial
state. If the DSR line changes state quickly several times in succession, Serial INSTR
DSR
not all line state changes necessarily result in event notifications.
Notifies the application that the Data Carrier Detect (DCD) line changed
Serial
state. If the DCD line changes state quickly several times in succession, Serial INSTR
DCD
not all line state changes necessarily result in event notifications.
Serial RI Notifies the application that the Ring Indicator (RI) input signal was Serial INSTR

© National Instruments 2873

 Functions

Event Resource
Description
Name Classes
asserted.
Notifies the application that at least one data byte has been received.
Each data character does not necessarily result in an event notification.
Serial In other words, if multiple data bytes arrive at once, you may get only
Serial INSTR
Character one event. After receiving this event, use the Serial Settings:Number of
Bytes at Serial Port property to query the serial port for the number of
bytes available.

Serial
Use the Serial VIs and functions to access the VISA VIs and functions that communicate
with devices connected to a serial port. Additional functions are also available on the
VISA palette.

The VIs and functions on this palette can return serial error codes.

Palette
Description
Object

VISA Initializes the serial port specified by VISA resource name to the specified settings.
Configure Wire data to the VISA resource name input to determine the polymorphic instance to
Serial Port use or manually select the instance.

VISA Write Writes the data from write buffer to the device or interface specified by VISA
Function resource name.
VISA Read Reads the specified number of bytes from the device or interface specified by VISA
Function resource name and returns the data in read buffer.
VISA Close
Closes a device session or event object specified by VISA resource name.
Function

VISA Bytes
Returns the number of bytes in the input buffer of the specified serial port.
at Serial

2874 ni.com
 Functions

Palette
Description
Object
Port

VISA Serial Sends a break on the specified output port. Wire data to the VISA resource name
Break input to determine the polymorphic instance to use or manually select the instance.

VISA Set I/O

Sets the size of the I/O buffer. Run the VISA Configure Serial Port VI first if you are
Buffer Size
setting the size of a serial port buffer.
Function
VISA Flush
I/O Buffer Flushes the I/O buffer specified by mask.
Function

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Instrument IO\Serial\Serial.lvproj

Vision and Motion

Refer to the NI Vision, NI Vision Acquisition Software, NI-Motion, and NI SoftMotion
help files, which you can access from the Help menu, for more information about
those VIs. If NI Vision Acquisition Software, NI-Motion, and NI SoftMotion are not
installed, you cannot access the help files. Install these additional packages from the
media included with LabVIEW.

Mathematics
Use the Mathematics VIs to perform many different kinds of mathematical analysis.
You also can interface real-world measurements to the mathematical algorithms in
order to obtain practical solutions.

© National Instruments 2875

 Functions

The Mathematics VIs support only explicit multiplication syntax. For example, to
multiply the variable x by 5, enter 5*x rather than 5x.

Note Many Mathematics VIs are available only in the LabVIEW Full and
Professional Development Systems. If you have the LabVIEW Base
Development System, you do not have the full set of the Mathematics VIs
described in this help file. A subset of the Mathematics VIs is available in the
LabVIEW Base Development System.

Palette Object Description

Use the Numeric VIs and functions to create and perform arithmetic and complex
mathematical operations on numbers and to convert numbers from one data type
Numeric
to another. Use the VIs and functions on the Elementary and Special Functions and
VIs palette to perform trigonometric and logarithmic functions.

Elementary &
Use the Elementary & Special Functions and VIs to evaluate common mathematical
Special
functions.
Functions

Linear Algebra Use the Linear Algebra VIs to perform matrix-related computations and analysis.

Fitting Use the Fitting VIs to perform curve fitting analysis or regression.

Interpolation
Use the Interpolation & Extrapolation VIs to perform 1D and 2D interpolation,
&
piecewise interpolation, polynomial interpolation, and Fourier interpolation.
Extrapolation

Integration & Use the Integration & Differentiation VIs to perform integration and differentiation
Differentiation procedures.

2876 ni.com
 Functions

Palette Object Description

Probability & Use the Probability and Statistics VIs to perform probability, descriptive statistics,
Statistics analysis of variance, and interpolation functions.

Use the Optimization VIs to determine local minima and maxima of real 1D or
Optimization
n-dimension functions.

Differential
Use the Differential Equations VIs to solve differential equations.
Equations

Geometry Use the Geometry VIs to manipulate coordinates and angles.

Polynomial Use the Polynomial VIs to perform calculations and evaluations with polynomials.

Scripts & Use the Scripts & Formulas VIs to evaluate mathematical formulae and expressions
Formulas on the block diagram.

Numeric
Use the Numeric VIs and functions to create and perform arithmetic and complex
mathematical operations on numbers and to convert numbers from one data type to
another. Use the VIs and functions on the Elementary and Special Functions and VIs
palette to perform trigonometric and logarithmic functions.

You also can access the following constants from this palette:

• positive infinity
• negative infinity
• machine epsilon
• not a number

© National Instruments 2877

 Functions

Palette
Description
Object
Add
Computes the sum of the inputs.
Function
Subtract
Computes the difference of the inputs.
Function
Multiply
Returns the product of the inputs.
Function
Divide
Computes the quotient of the inputs.
Function
Quotient &
Computes the integer quotient and the remainder of the inputs. This function
Remainder
rounds floor(x/y) to the nearest integer towards -inf.
Function

Conversion Use the Conversion VIs and functions to convert data types.

Increment
Adds 1 to the input value.
Function
Decrement
Subtracts 1 from the input value.
Function
Add Array
Elements Returns the sum of all the elements in numeric array.
Function
Multiply
Returns the product of all the elements in numeric array. If numeric array is an
Array
empty array, the function returns a value of 1. If numeric array contains only one
Elements
element, the function returns that element.
Function
Performs arithmetic on one or more numeric, array, cluster, or Boolean inputs. To
select the operation (Add, Multiply, AND, OR, or XOR), right-click the function and
Compound
select Change Mode from the shortcut menu. When you select this function from the
Arithmetic
Numeric palette, the default mode is Add. When you select this function from the
Boolean palette, the default mode is OR.

2878 ni.com
 Functions

Palette
Description
Object

Data
Use the Data Manipulation functions to modify the data types used in LabVIEW.
Manipulation

Absolute
Value Returns the absolute value of the input.
Function
Round To
Rounds the input to the nearest integer. If the value of the input is midway between
Nearest
two integers, the function returns the nearest even integer.
Function
Round
Toward
Truncates the input to the next lowest integer.
-Infinity
Function
Round
Toward
Rounds the input to the next highest integer.
+Infinity
Function
Scale By
Power Of 2 Multiplies x by 2 raised to the power of n.
Function

Use the Complex functions to create complex numbers from two values given in
Complex rectangular or polar and to break a complex number into its rectangular or polar
components.

Square Root
Computes the square root of the input value.
Function
Square
Computes the square of the input value.
Function
Negate
Negates the input value.
Function
Reciprocal
Divides 1 by the input value.
Function
Sign
Returns the sign of number.
Function

© National Instruments 2879

 Functions

Palette
Description
Object

Scaling Use the Scaling VIs to convert voltage readings to other temperature or strain units.

Numeric Use the numeric constant to pass a numeric value to the block diagram. Set this
Constant value by clicking inside the constant with the Operating tool and typing a value.
Enum Use the enumerated constant to create a list of string labels with corresponding
Constant integer values you can select on the block diagram.
Ring Use the ring constant to create a list of value pairs you can select on the block
Constant diagram. Each value pair consists of a numeric value and corresponding string label.
Random
Produces a double-precision, floating-point number between 0 and 1. The number
Number (0-1)
generated is greater than or equal to 0, but less than 1. The distribution is uniform.
Function

Random Generates a random value from a specified range. Wire data to the upper bound or
Number lower bound input to determine the polymorphic instance to use or manually select
(Range) the instance.

Use the Fixed-Point functions to manipulate the overflow status of a fixed-point

Fixed-Point
number.

Use the DBL numeric constant to pass a double-precision, floating-point numeric

DBL Numeric
value to the block diagram. Set this value by clicking inside the constant with the
Constant
Operating tool and typing a value.

Positive
Returns the value Inf (infinity).
Infinity
Negative
Returns the value -Inf (negative infinity).
Infinity
Represents the round-off error for a floating-point number with a given precision.
Machine
Use the machine epsilon constant to compare whether two floating-point numbers
Epsilon
are equivalent.

Not A
Returns the value NaN (not a number).
Number

2880 ni.com
 Functions

Palette
Description
Object
Constant
Math &
Scientific Use the Math & Scientific Constants to create LabVIEW applications.
Constants

Range Limits
Returns the maximum and minimum values of the input data type.
for Type

Use the Expression Node to calculate expressions that contain a single variable. The
following built-in functions are allowed in formulas: abs, acos, acosh, asin, asinh,
Expression
atan, atanh, ceil, cos, cosh, cot, csc, exp, expm1, floor, getexp, getman, int, intrz, ln,
Node
lnp1, log, log2, max, min, mod, rand, rem, sec, sign, sin, sinc, sinh, sizeOfDim, sqrt,
tan, tanh.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Numerics\Numeric Functions.vi

Elementary & Special Functions

Use the Elementary & Special Functions and VIs to evaluate common mathematical
functions.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Trigonometric Use this class of elementary functions to compute trigonometric functions and
Functions their inverses.

© National Instruments 2881

 Functions

Palette Object Description

Exponential Use this class of elementary functions to compute exponential and logarithmic
Functions functions.

Hyperbolic Use this class of elementary functions to compute hyperbolic functions and
Functions their inverses.

Use this class of elementary functions to compute common periodic waves at

Gating Functions
given points.

Use this class of elementary functions to compute discrete math functions for
Discrete Math
areas such as combinatorics and number theory.

Bessel Functions Use this class of special functions to compute Bessel-related functions.

Gamma
Use this class of special functions to compute Gamma-related functions.
Functions

Hypergeometric Use this class of special functions to compute functions based on the
Functions hypergeometric differential equation.

Use this class of special functions to compute complete and incomplete elliptic
Elliptic Integrals
integrals.

Exponential
Use this class of special functions to compute exponential integrals.
Integrals

Error Functions Use this class of special functions to compute Error-related functions.

2882 ni.com
 Functions

Palette Object Description

Elliptic &
Use this class of special functions to compute specific forms of elliptic integrals
Parabolic
or Weber functions.
Functions

Trigonometric Functions

Use this class of elementary functions to compute trigonometric functions and their
inverses.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Sine Function Computes the sine of x, where x is in radians.
Cosine Function Computes the cosine of x, where x is in radians.
Tangent Function Computes the tangent of x, where x is in radians.
Computes the secant of x, where x is in radians. Secant is the reciprocal of
Secant Function
cosine.
Computes the cosecant of x, where x is in radians. Cosecant is the
Cosecant Function
reciprocal of sine.
Computes the cotangent of x, where x is in radians. Cotangent is the
Cotangent Function
reciprocal of tangent.
Inverse Sine Function Computes the arcsine of x.
Inverse Cosine
Computes the arccosine of x.
Function
Inverse Tangent
Computes the arctangent of x.
Function
Inverse Secant
Computes the inverse secant of x.
Function
Inverse Cosecant Computes the inverse cosecant of x.

© National Instruments 2883

 Functions

Palette Object Description

Function
Inverse Cotangent
Computes the inverse cotangent of x.
Function
Sine & Cosine Computes both the sine and cosine of x, where x is in radians. Use this
Function function only when you need both results.
Sinc Function Computes the sine of x divided by x, where x is in radians.
Inverse Tangent (2
Computes the arctangent of y/x.
Input) Function

Sine Function

Computes the sine of x, where x is in radians.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• sin(x) —

sin(x) is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines sin(x):
sin(x) = sin(a) * cosh(b) + i(cos(a) * sinh(b))

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

2884 ni.com
 Functions

Functions\Trigonometric Functions\Sine.vi

Cosine Function

Computes the cosine of x, where x is in radians.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• cos(x) —

cos(x) is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines cos(x):

cos(x) = cos(a) * cosh(b) + i(-sin(a) * sinh(b))

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Tangent Function

Computes the tangent of x, where x is in radians.

The connector pane displays the default data types for this polymorphic function.

© National Instruments 2885

 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• tan(x) —

tan(x) is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines tan(x):

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Secant Function

Computes the secant of x, where x is in radians. Secant is the reciprocal of cosine.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• 1/cos(x) —

2886 ni.com
 Functions

1/cos(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Cosecant Function

Computes the cosecant of x, where x is in radians. Cosecant is the reciprocal of sine.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• 1/sin(x) —

1/sin(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

© National Instruments 2887

 Functions

Cotangent Function

Computes the cotangent of x, where x is in radians. Cotangent is the reciprocal of

tangent.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• 1/tan(x) —

1/tan(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Sine Function

Computes the arcsine of x.

If x is not complex and is less than –1 or greater than 1, the result is NaN. The
connector pane displays the default data types for this polymorphic function.

2888 ni.com
 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• arcsin(x) —

arcsin(x) is of the same numeric representation as x. When x is of the form x = a + bi, that is,
when x is complex, the following equation defines arcsin(x):

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Cosine Function

Computes the arccosine of x.

If x is not complex and is less than –1 or greater than 1, the result is NaN. The
connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• arccos(x) —

arccos(x) is of the same numeric representation as x. When x is of the form x = a + bi, that is,

© National Instruments 2889

 Functions

when x is complex, the following equation defines arccos(x):

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Tangent Function

Computes the arctangent of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• arctan(x) —

arctan(x) is of the same numeric representation as x. When x is of the form x = a + bi, that is,
when x is complex, the following equation defines arctan(x):

arctan(x) ranges from -pi/2 to pi/2.

2890 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Secant Function

Computes the inverse secant of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• arcsec(x) —

arcsec(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Cosecant Function

Computes the inverse cosecant of x.

The connector pane displays the default data types for this polymorphic function.

© National Instruments 2891

 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• arccsc(x) —

arccsc(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Cotangent Function

Computes the inverse cotangent of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• arccot(x) —

arccot(x) is of the same numeric representation as x.

2892 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Sine & Cosine Function

Computes both the sine and cosine of x, where x is in radians. Use this function only
when you need both results.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• sin(x) —

sin(x) is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines sin(x):
sin(x) = sin(a) * cosh(b) + i(cos(a) * sinh(b))
• cos(x) —

cos(x) is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines cos(x):
cos(x) = cos(a) * cosh(b) + i(-sin(a) * sinh(b))

Sinc Function

Computes the sine of x divided by x, where x is in radians.

© National Instruments 2893

 Functions

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• sin(x)/x —

sin(x)/x is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Tangent (2 Input) Function

Computes the arctangent of y/x.

This function can compute the arctangent for angles in any of the four quadrants of the
x-y plane, whereas the Inverse Tangent function computes the arctangent in only two
quadrants. The connector pane displays the default data types for this polymorphic
function.

Inputs/Outputs
• y—

2894 ni.com
 Functions

y can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• atan2(y,x) —

atan2(y,x) is the arctangent of y and x, in radians. atan2(y,x) falls in the range [-pi, pi]. When x or
y are complex, the following equation defines atan2(y,x):

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Exponential Functions

Use this class of elementary functions to compute exponential and logarithmic

functions.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Exponential
Computes the value of e raised to the x power, or the exponential of x.
Function
Exponential (Arg)
Computes 1 less than the value of e raised to the x power.
-1 Function

© National Instruments 2895

 Functions

Palette Object Description

Power Of 10
Computes 10 raised to the x power.
Function
Power Of 2
Computes 2 raised to the x power.
Function
Power Of X
Computes x raised to the y power.
Function
Y-th Root of X Returns the yth root of the input value x. If x is not complex, x must be greater
Function than or equal to zero unless y is an integer. Otherwise, the result is NaN.
Natural Logarithm
Computes the base e natural logarithm of x.
Function
Natural Logarithm
Computes the natural logarithm of (x + 1).
(Arg +1) Function
Logarithm Base
Computes the base 10 logarithm of x.
10 Function
Logarithm Base 2
Computes the base 2 logarithm of x.
Function
Logarithm Base X
Computes the base x logarithm of y.
Function

Exponential Function

Computes the value of e raised to the x power, or the exponential of x.

Note For very small values of x, the Exponential (Arg) -1 function is more
accurate than using this function then subtracting 1 from the output.

The connector pane displays the default data types for this polymorphic function.

2896 ni.com
 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• exp(x) —

exp(x) is of the same numeric representation as x. The following equation defines the
exponential exp(x):

exp(a+bi) = exp(a)(cos(b)+i sin(b))

when x is of the form x = a + bi, that is, when x is complex.

If x is a matrix, this function computes the exponential of x. When you wire matrix data
as an input to this function, a VI that includes subVIs that work with the matrix data
type replaces the function. The resulting VI has the same icon but contains a matrix-
specific algorithm. The node remains a VI if you disconnect the matrix from the
input(s). Wire other data types as inputs to restore the original function. If you wire a
data type to a function and that data type causes a basic math operation to fail, the
function returns an empty matrix or NaN.

Refer to the Matrix Exp VI for more information.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Exponential (Arg) -1 Function

Computes 1 less than the value of e raised to the x power.

When x is very small, this function is more accurate than using the Exponential
function then subtracting 1 from the output. The connector pane displays the default
data types for this polymorphic function.

© National Instruments 2897

 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• exp(x) -1 —

exp(x)-1 is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines
exp(x)-1:exp(x)-1 = (exp(a) * (cos(b)+i sin(b))) – 1

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Power Of 10 Function

Computes 10 raised to the x power.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• 10^x —

2898 ni.com
 Functions

10^x is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines
10^x:10^x = 10^a * 10^(bi) = 10^a * (cos(b * ln(10)) + i sin (b * ln(10)))

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Power Of 2 Function

Computes 2 raised to the x power.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• 2^x —

2^x is of the same numeric representation as x.

When x is of the form x = a + bi, that is, when x is complex, the following equation defines 2^x:
2^x = 2^a * 2^(bi) = 2^a * (cos(b * ln(2)) + i sin(b * ln(2)))

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

© National Instruments 2899

 Functions

Functions\Exponential Functions\Exponential.vi

Power Of X Function

Computes x raised to the y power.

If x is not complex, it must be greater than zero unless y is an integer value. Otherwise,
the result is NaN. If y is 0, x^y is 1 for all values of x, including 0. The connector pane
displays the default data types for this polymorphic function.

Inputs/Outputs
• y—

y can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• x^y —

x^y is x to the power of y.

When x and y are complex, the following equation defines x^y: x^y = exp(y * ln(x)) Refer to the
Exponential function and the Natural Logarithm function for more information.

When you wire matrix data as an input to this function, a VI that includes subVIs that
work with the matrix data type replaces the function. The resulting VI has the same
icon but contains a matrix-specific algorithm. The node remains a VI if you disconnect
the matrix from the input(s). Wire other data types as inputs to restore the original
function. If you wire a data type to a function and that data type causes a basic math
operation to fail, the function returns an empty matrix or NaN.

Refer to the Matrix Power VI for more information.

2900 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Y-th Root of X Function

Returns the yth root of the input value x. If x is not complex, x must be greater than or
equal to zero unless y is an integer. Otherwise, the result is NaN.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• y—

y can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• y-th root(x) —

y-th root(x) returns the yth root of x.

When x and y are complex, the following equation defines y-th root(x): y-th root(x) = exp((1/y) *
ln(x)) Refer to the Natural Logarithm function and the Exponential function for more
information.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

© National Instruments 2901

 Functions

Functions\Exponential Functions\Exponential.vi

Natural Logarithm Function

Computes the base e natural logarithm of x.

If x is 0, ln(x) is –∞. If x is not complex and is less than 0, ln(x) is NaN.

Note For very small values of x, the Natural Logarithm (Arg +1) function is
more accurate than adding 1 to x then using this function.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• ln(x) —

ln(x) is of the same numeric representation as x. When x is of the form x = a + bi, that is, when x is
complex, the following equation defines the natural logarithm ln(x): ln(x) = ln(|x|) + i arg(x)where
arg(x) is the phase of x over the interval . In other words, LabVIEW uses the
following equation:

When you wire matrix data as an input to this function, a VI that includes subVIs that
work with the matrix data type replaces the function. The resulting VI has the same
icon but contains a matrix-specific algorithm. The node remains a VI if you disconnect
the matrix from the input(s). Wire other data types as inputs to restore the original
function. If you wire a data type to a function and that data type causes a basic math
operation to fail, the function returns an empty matrix or NaN.

Refer to the Matrix Logarithm VI for more information.

2902 ni.com
 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Natural Logarithm (Arg +1) Function

Computes the natural logarithm of (x + 1).

When x is near 0, this function is more accurate than adding 1 to x then using the
Natural Logarithm function. If x is equal to –1, the result is –∞. If x is not complex and is
less than –1, the result is NaN. The connector pane displays the default data types for
this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• ln(x+1) —

ln(x+1) is of the same numeric representation as x. When x is of the form x = a + bi, that is, when
x is complex, the following equation defines ln(x+1): ln(x+1) = ln(|x + 1|) + i arctan2(b, a + 1)

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

© National Instruments 2903

 Functions

Logarithm Base 10 Function

Computes the base 10 logarithm of x.

If x is 0, log(x) is negative infinity. If x is not complex and is less than 0, log(x) is NaN.
The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• log(x) —

log(x) is of the same numeric representation as x. When x is of the form x = a + bi, that is, when x
is complex, the following equation defines log(x):

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Logarithm Base 2 Function

Computes the base 2 logarithm of x.

If x is 0, log2(x) is negative infinity. If x is not complex and is less than 0, log2(x) is NaN.
The connector pane displays the default data types for this polymorphic function.

2904 ni.com
 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• log2(x) —

log2(x) is of the same numeric representation as x. When x is of the form x = a + bi, that is, when
x is complex, the following equation defines log2(x):

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Logarithm Base X Function

Computes the base x logarithm of y.

(x>0, y>0). If y is 0, the output is –∞. When x and y are both non-complex and x is less
than or equal to 0, or y is less than 0, the output is NaN. The connector pane displays
the default data types for this polymorphic function.

Inputs/Outputs
• y—

y can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

© National Instruments 2905

 Functions

• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• logx(y) —

logx(y) is the logarithm of y to the base x. When x and y are complex, the following equation
defines logx(y):

logx(y) = ln(y)/ln(x)

Refer to the Natural Logarithm function for more information.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Exponential Functions\Exponential.vi

Hyperbolic Functions

Use this class of elementary functions to compute hyperbolic functions and their
inverses.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Hyperbolic Sine Function Computes the hyperbolic sine of x.
Hyperbolic Cosine Function Computes the hyperbolic cosine of x.
Hyperbolic Tangent Function Computes the hyperbolic tangent of x.
Hyperbolic Secant Function Computes the hyperbolic secant of x.
Hyperbolic Cosecant Function Computes the hyperbolic cosecant of x.

2906 ni.com
 Functions

Palette Object Description

Hyperbolic Cotangent Function Computes the hyperbolic cotangent of x.
Inverse Hyperbolic Sine Function Computes the inverse hyperbolic sine of x.
Inverse Hyperbolic Cosine Function Computes the inverse hyperbolic cosine of x.
Inverse Hyperbolic Tangent Function Computes the inverse hyperbolic tangent of x.
Inverse Hyperbolic Secant Function Computes the inverse hyperbolic secant of x.
Inverse Hyperbolic Cosecant Function Computes the inverse hyperbolic cosecant of x.
Inverse Hyperbolic Cotangent Function Computes the inverse hyperbolic cotangent of x.

Hyperbolic Sine Function

Computes the hyperbolic sine of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• sinh(x) —

sinh(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

© National Instruments 2907

 Functions

Hyperbolic Cosine Function

Computes the hyperbolic cosine of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• cosh(x) —

cosh(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Hyperbolic Tangent Function

Computes the hyperbolic tangent of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

2908 ni.com
 Functions

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• tanh(x) —

tanh(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Hyperbolic Secant Function

Computes the hyperbolic secant of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• sech(x) —

sech(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

© National Instruments 2909

 Functions

Functions\Trigonometric Functions\Sine.vi

Hyperbolic Cosecant Function

Computes the hyperbolic cosecant of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• csch(x) —

csch(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Hyperbolic Cotangent Function

Computes the hyperbolic cotangent of x.

The connector pane displays the default data types for this polymorphic function.

2910 ni.com
 Functions

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• coth(x) —

coth(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Hyperbolic Sine Function

Computes the inverse hyperbolic sine of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• argsinh(x) —

argsinh(x) is of the same numeric representation as x.

© National Instruments 2911

 Functions

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Hyperbolic Cosine Function

Computes the inverse hyperbolic cosine of x.

If x is not complex and is less than 1, the result is NaN. The connector pane displays the
default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• argcosh(x) —

argcosh(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Hyperbolic Tangent Function

Computes the inverse hyperbolic tangent of x.

2912 ni.com
 Functions

If x is not complex and is less than –1 or greater than 1, the result is NaN. The
connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• argtanh(x) —

argtanh(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Hyperbolic Secant Function

Computes the inverse hyperbolic secant of x.

If x is not complex and is less than 0 or greater than 1, the result is NaN. The connector
pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

© National Instruments 2913

 Functions

• argsech(x) —

argsech(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Inverse Hyperbolic Cosecant Function

Computes the inverse hyperbolic cosecant of x.

The connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• argcsch(x) —

argcsch(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

2914 ni.com
 Functions

Inverse Hyperbolic Cotangent Function

Computes the inverse hyperbolic cotangent of x.

If x is not complex and is greater than –1 and less than 1, the result is NaN. The
connector pane displays the default data types for this polymorphic function.

Inputs/Outputs
• x—

x can be a scalar number, array or cluster of numbers, array of clusters of numbers, and so on.

• argcoth(x) —

argcoth(x) is of the same numeric representation as x.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Elementary & Special

Functions\Trigonometric Functions\Sine.vi

Gating Functions

Use this class of elementary functions to compute common periodic waves at given
points.

The VIs on this palette can return mathematics error codes.

© National Instruments 2915

 Functions

Palette Object Description

Spike Function VI Generates the spike function for any real number x.

Square Function VI Generates the square function for any real number x.

Step Function VI Generates the step function for any real number x.

Spike Function VI

Generates the spike function for any real number x.

Inputs/Outputs
• x—

x is any real number.

• spike(x) —

spike(x) is the value of spike(x) for the given value of x.

The following equation defines the spike function:

spike(x) = 1, if 0 ≤ x < 1 and 0 elsewhere.

Note You can define more complex functions by varying and combining the
Step Function, Spike Function, and Square Function VIs, respectively.

The following illustration shows the graph for spike(x) – spike(–x) in the interval (–4.0,
4.0).

2916 ni.com
 Functions

Square Function VI

Generates the square function for any real number x.

Inputs/Outputs
• x—

x is any real number.

• square(x) —

square(x) is the value of square(x) for the given value of x.

The following equation defines the square function.

square(x) = 1, if 2n ≤ x < 2n + 1 and 0 elsewhere,where n is an integer.

Note You can define more complex functions by varying and combining the
Step Function, Spike Function, and Square Function VIs, respectively.

The following illustration shows the graph for square(x) * square(x – 0.8) in the interval
(–4.0, 4.0).

© National Instruments 2917

 Functions

Step Function VI

Generates the step function for any real number x.

Inputs/Outputs
• x—

x is any real number.

• step(x) —

step(x) is the value of step(x) for the given value of x.

The following equation defines the step function.

step(x) = 0 if x < 0 and 1 elsewhere

Note You can define more complex functions by varying and combining the
Step Function, Spike Function, and Square Function VIs, respectively.

The following illustration shows the graph for step(x) + spike(x) in the interval (–4.0,
4.0)

2918 ni.com
 Functions

Discrete Math

Use this class of elementary functions to compute discrete math functions for areas
such as combinatorics and number theory.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Gcd Computes the greatest common divisor of the input values.

Lcm Computes the least common multiple of the input values.

Factorial Computes the factorial of n.

Prime Factor Computes the prime factorization of an integer.

Check Prime Checks whether a number is a prime number.

© National Instruments 2919

 Functions

Palette Object Description

Computes the number of ways to obtain an ordered subset of k elements from

Permute
a set of n elements.

Binomial
Calculates the binomial coefficient for nonnegative integer values of n and k.
Coefficient VI

Continued Fraction Evaluates the continued fraction of two sequences (a[0], a[1], …, a[n]) and
VI (b[0], b[1], …, b[n]).

(Riemann) Zeta
Computes the zeta function.
Function

Gcd

Computes the greatest common divisor of the input values.

Inputs/Outputs
• x—

x is an integer.

• y—

y is an integer.

• gcd(x,y) —

gcd(x,y) returns the greatest common divisor of x and y.

gcd(x,y) is the largest divisor common to x and y.

2920 ni.com
 Functions

To compute gcd(x,y), consider the prime factorizations of x and y:

x = Πi piai y = Πi pibi

where pi are all the prime factors of x and y. If pi does not occur in a factorization, the
corresponding exponent is 0. gcd(x,y) then is given by:

gcd(x,y) = Πi pimin(ai , bi)

For example, the prime factorizations of 12 and 30 are given by:

12 = 2² × 31 × 50 30 = 21 × 31 × 51

so

gcd(12, 30) = 21 × 31 × 50 = 6

Lcm

Computes the least common multiple of the input values.

Inputs/Outputs
• x—

x is an integer.

• y—

y is an integer.

• lcm(x,y) —

lcm(x,y) returns the least common multiple of x and y.

© National Instruments 2921

 Functions

lcm(x,y) is the smallest integer m for which there exist integers c and d such that

x×c=y×d=m

To compute lcm(x,y), consider the prime factorizations of x and y:

x = Πi piai y = Πi pibi

where pi are all the prime factors of x and y. If pi does not occur in a factorization, the
corresponding exponent is 0. lcm(x,y) then is given by:

lcm(x,y) = Πi pimax(ai, bi)

For example, the prime factorizations of 12 and 30 are given by:

12 = 2² × 31 × 50 30 = 21 × 31 × 51

so

lcm(12,30) = 2² × 31 × 51 = 60

Factorial

Computes the factorial of n.

Inputs/Outputs
• n—

n is the input argument.

• n! —

n! returns the factorial of n.

2922 ni.com
 Functions

The following equation defines the factorial function.

Prime Factor

Computes the prime factorization of an integer.

Inputs/Outputs
• n—

n is an integer the VI factorizes. If n is negative, the VI factorizes the absolute value of n.

• Prime Factors —

Prime Factors returns an array of prime numbers whose product equals n.

Check Prime

Checks whether a number is a prime number.

Inputs/Outputs
• n—

n specifies an integer.

• prime? —

prime? returns TRUE if n is a prime number.

© National Instruments 2923

 Functions

Permute

Computes the number of ways to obtain an ordered subset of k elements from a set of
n elements.

Inputs/Outputs
• n—

n is an unsigned integer.

• k—

k is an unsigned integer.

• nPk —

nPk returns the number of ordered subsets of k elements that you can obtain from a set of n
elements.

Binomial Coefficient VI

Calculates the binomial coefficient for nonnegative integer values of n and k.

Inputs/Outputs
• n—

n is any nonnegative integer.

• k—

k is any nonnegative integer.

2924 ni.com
 Functions

• binomial coefficient (n,k) —

binomial coefficient (n,k) is the result of the calculation of the binomial coefficient for the given
values of n and k.

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

The following equation defines the binomial coefficient.

Binomial coefficients can have many digits, even in the case of relatively small
numbers n and k. The data type most suited for the binomial coefficient is a double
real. You can directly calculate the factorial functions, n!, k!, and (n – k)!, with the
(Incomplete) Gamma Function VI.

Continued Fraction VI

Evaluates the continued fraction of two sequences (a[0], a[1], …, a[n]) and (b[0], b[1],
…, b[n]).

Inputs/Outputs
• A—

A is the 1D array of the numerator part of the continued fraction.

• B—

B is the 1D array of the denominator part of the continued fraction.

• result —

© National Instruments 2925

 Functions

result is a real value representing the result of the continued fraction.

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

The following equation defines the evaluated sequences.

Continued fractions are valuable tools for calculating special functions.

(Riemann) Zeta Function

Computes the zeta function.

Inputs/Outputs
• x—

x is the input argument.

• z(x) —

z(x) returns the value of the zeta function.

The following formula defines the Riemann zeta function ζ(x).

2926 ni.com
 Functions

Bessel Functions

Use this class of special functions to compute Bessel-related functions.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Bessel Function Jv Computes the Bessel function of the first kind.

Computes the Bessel function of the second kind, also known as the
Bessel Function Yv
Neumann function.

Computes the Hankel function, which is also known as the Bessel function of
Hankel Function Hv
the third kind.

Modified Bessel
Computes the modified Bessel function of the first kind.
Function Iv

Modified Bessel
Computes the modified Bessel function of the second kind.
Function Kn

Spherical Bessel
Calculates the spherical Bessel function of the first kind.
Function jn

Spherical Bessel
Calculates the spherical Bessel function of the second kind.
Function yn

Spherical Hankel Computes the spherical Hankel function, which is also known as the
Function hn spherical Bessel function of the third kind.

© National Instruments 2927

 Functions

Palette Object Description

Airy Functions Computes the Airy functions Ai(x) and Bi(x).

Struve Function Computes the Struve function.

Kelvin Functions be Computes the complex Kelvin function of the first kind.

Kelvin Functions ke Computes the complex Kelvin function of the second kind.

Bessel Function Jv

Computes the Bessel function of the first kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• v—

v specifies the order of the Bessel function.

• Jv(x) —

Jv(x) returns the value of the Bessel function of the first kind.

The Bessel function of the first kind of order v, Jv, is a solution of the following
differential equation.

2928 ni.com
 Functions

The function is defined according to the following intervals for the input values.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any integer value of order v, the function is defined for all real values of x.
Otherwise, the function is defined for nonnegative real values of x.

Bessel Function Yv

Computes the Bessel function of the second kind, also known as the Neumann
function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• v—

v specifies the order of the Bessel function.

• Yv(x) —

Yv(x) returns the value of the Bessel function of the second kind.

The Bessel function of the second kind of order v, Yv, is a solution of the following
differential equation.

The function is defined according to the following intervals for the input values.

© National Instruments 2929

 Functions

LabVIEW supports the entire domain of this function that produces real-valued results.
For any real value of order v, the function is defined for positive real values of x.

Hankel Function Hv

Computes the Hankel function, which is also known as the Bessel function of the third
kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• v—

v specifies the order of the Hankel function.

• type —

type specifies the type of the Hankel function.

0 First Kind—Computes the Hankel function of the first kind.

1 Second Kind—Computes the Hankel function of the second kind.

• Hv(x) —

Hv(x) returns the value of the Hankel function.

The following equation defines the Hankel function of the first kind of order v.

2930 ni.com
 Functions

The following equation defines the Hankel function of the second kind of order v.

where Jv is a Bessel function of the first kind and Yv is a Bessel function of the second
kind.

The following intervals for the input values of the VI define the Hankel function.

For any real value of order v, LabVIEW supports positive real values of x.

Modified Bessel Function Iv

Computes the modified Bessel function of the first kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• v—

v specifies the order of the Bessel function.

• Iv(x) —

Iv(x) returns the value of the modified Bessel function of the first kind.

The modified Bessel function of the first kind of order v, Iv, also known as the
hyperbolic Bessel function of the first kind, is a solution of the following differential
equation.

© National Instruments 2931

 Functions

The function is defined according to the following intervals for the input values.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any integer value of order v, the function is defined for all real values of x. For any
noninteger value of order v, the function is defined for nonnegative real values of x.

Modified Bessel Function Kn

Computes the modified Bessel function of the second kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n specifies the order of the modified Bessel function.

• Kn(x) —

Kn(x) returns the value of the modified Bessel function of the second kind.

The modified Bessel function of the second kind of order n, Kn, also known as the
hyperbolic Bessel function of the second kind, is a solution of the following differential
equation.

The function is defined according to the following intervals for the input values.

2932 ni.com
 Functions

LabVIEW supports the entire domain of this function that produces real-valued results.
For any integer value of order n, the function is defined for nonnegative real values of
x.

Spherical Bessel Function jn

Calculates the spherical Bessel function of the first kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n specifies the order of the spherical Bessel function.

• jn(x) —

jn(x) returns the value of the spherical Bessel function of the first kind.

The spherical Bessel function of the first kind of order n, jn is a solution to the
following differential equation.

The following equation shows the relationship of the spherical Bessel function of the
first kind to the Bessel function of the first kind.

The function is defined according to the following intervals for the input values.

© National Instruments 2933

 Functions

LabVIEW supports the entire domain of this function that produces real-valued results.
For any integer value of order n, the function is defined for nonnegative real values of
x.

Spherical Bessel Function yn

Calculates the spherical Bessel function of the second kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n specifies the order of the spherical Bessel function.

• yn(x) —

yn(x) returns the value of the spherical Bessel function of the second kind.

The spherical Bessel function of the second kind of order n, yn is a solution to the
following differential equation.

The following equation shows the relationship of the spherical Bessel function of the
second kind to the Bessel function of the second kind.

The function is defined according to the following intervals for the input values.

2934 ni.com
 Functions

LabVIEW supports the entire domain of this function that produces real-valued results.
For any integer value of order n, the function is defined for nonnegative real values of
x.

Spherical Hankel Function hn

Computes the spherical Hankel function, which is also known as the spherical Bessel
function of the third kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n specifies the order of the spherical Hankel function.

• type —

type specifies the type of the spherical Hankel function.

0 First Kind—Computes the spherical Hankel function of the first kind.

1 Second Kind—Computes the spherical Hankel function of the second kind.

• hn(x) —

hn(x) returns the value of the spherical Hankel function.

The following equation defines the spherical Hankel function of the first kind of order
n.

© National Instruments 2935

 Functions

The following equation defines the spherical Hankel function of the second kind of
order n.

where jn is a spherical Bessel function of the first kind and yn is a spherical Bessel
function of the second kind.

The following intervals for the input values of the VI define the spherical Hankel
function.

For any integer value of order n, LabVIEW supports nonnegative real values of x.

Airy Functions

Computes the Airy functions Ai(x) and Bi(x).

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• Ai(x) —

Ai(x) returns the value of the Airy function Ai.

• Bi(x) —

Bi(x) returns the value of the Airy function Bi.

2936 ni.com
 Functions

The Airy functions Ai and Bi are solutions to the Airy differential equation, which is
given by the following equation.

Struve Function

Computes the Struve function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• v—

v is the index parameter.

• Hv(x) —

Hv(x) returns the value of the Struve function.

The Struve function of order v, Hv(x) is a solution of the following differential

equation.

The function is defined according to the following intervals for the input values.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any integer value of order v, the function is defined for all real values of x.
Otherwise, the function is defined for nonnegative real values of x.

© National Instruments 2937

 Functions

Kelvin Functions be

Computes the complex Kelvin function of the first kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n specifies the order of the Kelvin function.

• ber(x) + bei(x)i —

ber(x) + bei(x)i returns the complex value of the Kelvin function of the first kind.

The complex-valued Kelvin function of the first kind of order v is a solution of the
following complex-valued differential equation.

The real and imaginary parts of the Kelvin function of the first kind of order v are
solutions of the following differential equation.

The function is defined according to the following intervals for the input values.

For any integer value of order n, the function is defined for all real values of x.

2938 ni.com
 Functions

Kelvin Functions ke

Computes the complex Kelvin function of the second kind.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n specifies the order of the Kelvin function.

• ker(x) + kei(x)i —

ker(x) + kei(x)i returns the complex value of the Kelvin function of the second kind.

The complex-valued Kelvin function of the second kind of order v is a solution of the
following complex-valued differential equation.

The real and imaginary parts of the Kelvin function of the second kind of order v are
solutions of the following differential equation.

The function is defined according to the following intervals for the input values.

For any integer value of order n, the function is defined for positive real values of x.

© National Instruments 2939

 Functions

Gamma Functions

Use this class of special functions to compute Gamma-related functions.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Factorial Computes the factorial of n.

Evaluates the gamma function and regularized incomplete gamma

(Incomplete) Gamma
function. You must manually select the polymorphic instance you want to
Function
use.

Stirling's Formula Computes the Stirling approximation to the gamma function.

(Incomplete) Beta Evaluates the beta function and regularized incomplete beta function. You
Function must manually select the polymorphic instance you want to use.

Logarithm of Factorial Computes the natural logarithm of a factorial.

Logarithm of Complete
Computes the natural logarithm of the complete gamma function.
Gamma Function

Complementary
Incomplete Gamma Computes the regularized complementary incomplete gamma function.
Function

Psi (Digamma)
Computes the psi, or digamma, function.
Function

2940 ni.com
 Functions

Factorial

Computes the factorial of n.

Inputs/Outputs
• n—

n is the input argument.

• n! —

n! returns the factorial of n.

The following equation defines the factorial function.

(Incomplete) Gamma Function

Evaluates the gamma function and regularized incomplete gamma function. You must
manually select the polymorphic instance you want to use.

• Gamma Function VI
• Incomplete Gamma Function VI

Gamma Function

The following equation defines the gamma function.

© National Instruments 2941

 Functions

The gamma function is related to the factorial function by the identity gamma(n + 1) =
n! for integer n.

Incomplete Gamma Function

The following equation defines the regularized incomplete gamma function.

The following intervals for the input values define the function.

The following illustration shows the regularized incomplete gamma functions with a =
1, 2, 3, and 4 from top to bottom.

Gamma Function VI
Evaluates the gamma function and regularized incomplete gamma function. You must
manually select the polymorphic instance you want to use.

2942 ni.com
 Functions

Inputs/Outputs
• x—

x is the real input of the gamma function.

• g(x) —

g(x) is the result of the gamma function for the given value of x.

Gamma Function

The following equation defines the gamma function.

The gamma function is related to the factorial function by the identity gamma(n + 1) =
n! for integer n.

Incomplete Gamma Function

The following equation defines the regularized incomplete gamma function.

The following intervals for the input values define the function.

The following illustration shows the regularized incomplete gamma functions with a =
1, 2, 3, and 4 from top to bottom.

© National Instruments 2943

 Functions

Incomplete Gamma Function VI

Evaluates the gamma function and regularized incomplete gamma function. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• x—

x is the real input of the incomplete gamma function. x must be nonnegative.

• a—

a is the upper limit of the regularized incomplete gamma function. The default value is Inf.

• g(x, a) —

g(x, a) is the result of the regularized incomplete gamma function for the given values of x and a.

Gamma Function

The following equation defines the gamma function.

2944 ni.com
 Functions

The gamma function is related to the factorial function by the identity gamma(n + 1) =
n! for integer n.

Incomplete Gamma Function

The following equation defines the regularized incomplete gamma function.

The following intervals for the input values define the function.

The following illustration shows the regularized incomplete gamma functions with a =
1, 2, 3, and 4 from top to bottom.

Stirling's Formula

Computes the Stirling approximation to the gamma function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

© National Instruments 2945

 Functions

• Stirling(x) —

Stirling(x) returns the value of the Stirling function.

The following approximation defines the Stirling approximation to the gamma

function.

The function is defined according to the following interval for the input value.

LabVIEW supports the entire domain of this function that produces real-valued results.
The function is defined for nonnegative real values of x.

(Incomplete) Beta Function

Evaluates the beta function and regularized incomplete beta function. You must
manually select the polymorphic instance you want to use.

• Beta Function VI
• Incomplete Beta Function VI

Beta Function

The following equation defines the beta function.

The following intervals for the input values define the function.

2946 ni.com
 Functions

Incomplete Beta Function

The following equation defines the regularized incomplete beta function.

The following intervals for the input values define the function.

For any real nonnegative value of upper limit a ≤ 1, the function is defined for all real
nonnegative values of x and y.

Beta Function VI
Evaluates the beta function and regularized incomplete beta function. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• x—

x is the first argument of the beta function. x must be nonnegative.

• y—

y is the second argument of the beta function. y must be nonnegative.

• b(x, y) —

b(x, y) is the result of the beta function for the given values of x and y.

Beta Function

© National Instruments 2947

 Functions

The following equation defines the beta function.

The following intervals for the input values define the function.

Incomplete Beta Function

The following equation defines the regularized incomplete beta function.

The following intervals for the input values define the function.

For any real nonnegative value of upper limit a ≤ 1, the function is defined for all real
nonnegative values of x and y.

Incomplete Beta Function VI

Evaluates the beta function and regularized incomplete beta function. You must
manually select the polymorphic instance you want to use.

Inputs/Outputs
• x—

x is the first argument of the beta function. x must be nonnegative.

2948 ni.com
 Functions

• y—

y is the second argument of the beta function. y must be nonnegative.

• a—

a is the upper limit of the regularized incomplete beta integral and is a real number between 0
and 1. The default value is 1.

• b(x, y, a) —

b(x, y, a) is the result of the regularized incomplete beta function for the given values of x, y, and
a.

Beta Function

The following equation defines the beta function.

The following intervals for the input values define the function.

Incomplete Beta Function

The following equation defines the regularized incomplete beta function.

The following intervals for the input values define the function.

For any real nonnegative value of upper limit a ≤ 1, the function is defined for all real
nonnegative values of x and y.

© National Instruments 2949

 Functions

Logarithm of Factorial

Computes the natural logarithm of a factorial.

Inputs/Outputs
• n—

n is the input argument.

• ln(n!) —

ln(n!) returns the natural log of the factorial.

Logarithm of Complete Gamma Function

Computes the natural logarithm of the complete gamma function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• ln(g(x)) —

ln(g(x)) returns the natural logarithm of the complete gamma function.

Complementary Incomplete Gamma Function

Computes the regularized complementary incomplete gamma function.

2950 ni.com
 Functions

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• a—

a is the lower limit of the regularized complementary incomplete gamma integral.

• 1 - g(x, a) —

1 - g(x, a) returns the value of the regularized complementary incomplete gamma function.

The following equation defines the complement of the regularized incomplete gamma
function.

The complement of the regularized incomplete gamma function is related to the

regularized incomplete gamma function by the following identity.

The regularized incomplete gamma function is defined according to the following

intervals for the input values.

For any positive real value of lower limit a, the regularized incomplete gamma function
is defined for nonnegative real values of x.

Psi (Digamma) Function

Computes the psi, or digamma, function.

© National Instruments 2951

 Functions

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• y(x) —

y(x) returns the value of the psi function.

The following equation defines the psi function.

Hypergeometric Functions

Use this class of special functions to compute functions based on the hypergeometric
differential equation.

The VIs on this palette can return mathematics error codes.

Palette
Description
Object

Gauss Computes the Gauss hypergeometric function F(x, a, b, c) according to the input
Function argument and parameters you specify.

Kummer
Computes the Kummer, or confluent hypergeometric, function.
Function

2952 ni.com
 Functions

Palette
Description
Object

Tricomi
Computes the Tricomi, or associated confluent hypergeometric, function.
Function

Gauss Function

Computes the Gauss hypergeometric function F(x, a, b, c) according to the input

argument and parameters you specify.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• a—

a is the first parameter of the Gauss hypergeometric function.

• b—

b is the second parameter of the Gauss hypergeometric function.

• c—

c is the third parameter of the Gauss hypergeometric function.

• F(x, a, b, c) —

F(x, a, b, c) returns the value of the Gauss hypergeometric function.

The Gauss hypergeometric function F(x, a, b, c) is a solution of the following

differential equation:

© National Instruments 2953

 Functions

The function is defined according to the following intervals for the input values.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any real value of a, b, and c, the function is defined for real values of x < 1. For real
values of a, b, and c, such that c > a + b, the domain of x is extended to include 1.

Kummer Function

Computes the Kummer, or confluent hypergeometric, function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• a—

a is the first parameter of the Kummer function.

• b—

b is the second parameter of the Kummer function.

• M(x, a, b) —

M(x, a, b) returns the value of the Kummer function.

The Kummer function is a solution of the following differential equation.

2954 ni.com
 Functions

The function is defined according to the following intervals for the input values.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any real value of a and any real value of b except nonpositive integers, the function
is defined for all real values of x.

Tricomi Function

Computes the Tricomi, or associated confluent hypergeometric, function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• a—

a is the first parameter of the Tricomi function.

• b—

b is the second parameter of the Tricomi function.

• U(x, a, b) —

U(x, a, b) returns the value of the Tricomi function.

The Tricomi function U(x, a, b) is a solution of the following differential equation:

© National Instruments 2955

 Functions

Elliptic Integrals

Use this class of special functions to compute complete and incomplete elliptic
integrals.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Elliptic Integral of Computes the Legendre elliptic integral of the first kind. You must manually
the 1st kind select the polymorphic instance you want to use.

Elliptic Integral of Computes the Legendre elliptic integral of the second kind. You must manually
the 2nd kind select the polymorphic instance you want to use.

Elliptic Integral of the 1st kind

Computes the Legendre elliptic integral of the first kind. You must manually select the
polymorphic instance you want to use.

• Complete Elliptic Integral K VI

• Incomplete Elliptic Integral F VI

Complete Elliptic Integral K

The following equation defines the complete elliptic integral of the first kind.

2956 ni.com
 Functions

where k is the square of the elliptic modulus.

Incomplete Elliptic Integral F

The following equation defines the incomplete elliptic integral of the first kind.

where k is the square of the elliptic modulus and a is the upper limit, or amplitude, of
the integral.

The following intervals for the input values define the function.

LabVIEW supports the entire domain of this function that produces real-valued results.
For a real value of upper limit a, the function is defined for all real values of k in the
unit interval.

Complete Elliptic Integral K VI

Computes the Legendre elliptic integral of the first kind. You must manually select the
polymorphic instance you want to use.

Inputs/Outputs
• k—

k is the square of the elliptic modulus. k is a real number between 0 and 1.

• K(k) —

K(k) is the value of the complete elliptic integral of the first kind.

© National Instruments 2957

 Functions

Complete Elliptic Integral K

The following equation defines the complete elliptic integral of the first kind.

where k is the square of the elliptic modulus.

Incomplete Elliptic Integral F

The following equation defines the incomplete elliptic integral of the first kind.

where k is the square of the elliptic modulus and a is the upper limit, or amplitude, of
the integral.

The following intervals for the input values define the function.

LabVIEW supports the entire domain of this function that produces real-valued results.
For a real value of upper limit a, the function is defined for all real values of k in the
unit interval.

Incomplete Elliptic Integral F VI

Computes the Legendre elliptic integral of the first kind. You must manually select the
polymorphic instance you want to use.

2958 ni.com
 Functions

Inputs/Outputs
• k—

k is the square of the elliptic modulus. k is a real number between 0 and 1.

• a—

a is the amplitude of the function, which is the upper limit of the integral. The default value is Pi/
2.

• F(k, a) —

F(k, a) is the value of the incomplete elliptic integral of the first kind.

Complete Elliptic Integral K

The following equation defines the complete elliptic integral of the first kind.

where k is the square of the elliptic modulus.

Incomplete Elliptic Integral F

The following equation defines the incomplete elliptic integral of the first kind.

where k is the square of the elliptic modulus and a is the upper limit, or amplitude, of
the integral.

The following intervals for the input values define the function.

LabVIEW supports the entire domain of this function that produces real-valued results.

© National Instruments 2959

 Functions

For a real value of upper limit a, the function is defined for all real values of k in the
unit interval.

Elliptic Integral of the 2nd kind

Computes the Legendre elliptic integral of the second kind. You must manually select
the polymorphic instance you want to use.

• Complete Elliptic Integral E VI

• Incomplete Elliptic Integral E VI

Complete Elliptic Integral E

The following equation defines the complete elliptic integral of the second kind.

where k is the square of the elliptic modulus.

Incomplete Elliptic Integral E

The following equation defines the incomplete elliptic integral of the second kind.

where k is the square of the elliptic modulus and a is the upper limit, or amplitude, of
the integral.

The following intervals for the input values define the function.

2960 ni.com
 Functions

LabVIEW supports the entire domain of this function that produces real-valued results.
For any real value of upper limit a, the function is defined for all real values of k in the
unit interval.

Complete Elliptic Integral E VI

Computes the Legendre elliptic integral of the second kind. You must manually select
the polymorphic instance you want to use.

Inputs/Outputs
• k—

k is the square of the elliptic modulus. k is a real number between 0 and 1.

• E(k) —

E(k) is the value of the complete elliptic integral of the second kind.

Complete Elliptic Integral E

The following equation defines the complete elliptic integral of the second kind.

where k is the square of the elliptic modulus.

Incomplete Elliptic Integral E

The following equation defines the incomplete elliptic integral of the second kind.

© National Instruments 2961

 Functions

where k is the square of the elliptic modulus and a is the upper limit, or amplitude, of
the integral.

The following intervals for the input values define the function.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any real value of upper limit a, the function is defined for all real values of k in the
unit interval.

Incomplete Elliptic Integral E VI

Computes the Legendre elliptic integral of the second kind. You must manually select
the polymorphic instance you want to use.

Inputs/Outputs
• k—

k is the square of the elliptic modulus. k is a real number between 0 and 1.

• a—

a is the amplitude of the function, which is the upper limit of the integral. The default value is Pi/
2.

• E(k, a) —

E(k, a) is the value of the incomplete elliptic integral of the second kind.

Complete Elliptic Integral E

2962 ni.com
 Functions

The following equation defines the complete elliptic integral of the second kind.

where k is the square of the elliptic modulus.

Incomplete Elliptic Integral E

The following equation defines the incomplete elliptic integral of the second kind.

where k is the square of the elliptic modulus and a is the upper limit, or amplitude, of
the integral.

The following intervals for the input values define the function.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any real value of upper limit a, the function is defined for all real values of k in the
unit interval.

Exponential Integrals

Use this class of special functions to compute exponential integrals.

The VIs on this palette can return mathematics error codes.

© National Instruments 2963

 Functions

Palette Object Description

Exponential Integral Computes the exponential integral function.

Sine Integral Evaluates the sine integral for any real number x.

Cosine Integral Evaluates the cosine integral for any real nonnegative number x.

Dilogarithm Computes the dilogarithm function, or Spence's Integral.

Hyperbolic Sine Integral Computes the hyperbolic sine integral function.

Hyperbolic Cosine Integral Computes the hyperbolic cosine integral function.

Exponential Integral

Computes the exponential integral function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• n—

n is the exponent parameter.

• En(x) —

2964 ni.com
 Functions

En(x) returns the value of the exponential integral function.

The following equation defines the exponential integral function.

The following intervals for the input values define the exponential integral function.

LabVIEW supports the entire domain of this function that produces real-valued results.
For any nonnegative integer value of order n, the function is defined for nonnegative
real values of x.

Sine Integral

Evaluates the sine integral for any real number x.

Inputs/Outputs
• x—

x is any real number.

• Si(x) —

Si(x) is the result of the calculation of the sine integral for the given value of x.

The following equation defines the sine integral.

© National Instruments 2965

 Functions

where Si is the sine integral.

The following illustration shows the graph of the sine integral in the interval (0, 15).

Cosine Integral

Evaluates the cosine integral for any real nonnegative number x.

Inputs/Outputs
• x—

x is any real nonnegative number. If x is negative, the VI uses the absolute value of x.

• Ci(x) —

Ci(x) is the result of the calculation of the cosine integral for the given value of x.

The following equation defines the cosine integral.

where Ci is the cosine integral and γ is the Euler constant.

2966 ni.com
 Functions

The following illustration shows the graph of the cosine integral in the interval (0, 15).

Dilogarithm

Computes the dilogarithm function, or Spence's Integral.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• diln(x) —

diln(x) returns the value of the dilogarithm function.

The following equation defines the dilogarithm and the Spence's Integral.

where F(x) is the Spence's Integral and diln(x) is the dilogarithm.

The following intervals for the input values define the dilogarithm function.

© National Instruments 2967

 Functions

The function is defined for nonnegative real values of x.

Hyperbolic Sine Integral

Computes the hyperbolic sine integral function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• Shi(x) —

Shi(x) returns the value of the hyperbolic sine integral.

The following equation defines the hyperbolic sine integral function.

Hyperbolic Cosine Integral

Computes the hyperbolic cosine integral function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

2968 ni.com
 Functions

• Chi(x) —

Chi(x) returns the value of the hyperbolic cosine integral.

The following equation defines the hyperbolic cosine integral function.

where γ is Euler's constant.

Error Functions

Use this class of special functions to compute Error-related functions.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Error Function Computes the error function.

Error Function
Computes the error function complement.
Complement

Scaled Error Function Computes the scaled complementary error function associated with a
Complement normal distribution.

Computes the inverse of the error function associated with a normal

Inverse Error Function
distribution.

© National Instruments 2969

 Functions

Palette Object Description

Inverse Error Function Computes the inverse of the complementary error function associated
Complement with a normal distribution.

Fresnel Integrals Computes the Fresnel cosine and sine integral functions.

Dawson's Integral Computes the Dawson integral.

Error Function

Computes the error function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• erf(x) —

erf(x) returns the value of the error function.

The following equation defines the error function.

Error Function Complement

Computes the error function complement.

2970 ni.com
 Functions

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• 1 - erf(x) —

1 - erf(x) returns the value of the error function complement.

The following equation defines the error function complement.

Scaled Error Function Complement

Computes the scaled complementary error function associated with a normal

distribution.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• scaled erfc(x) —

scaled erfc(x) returns the value of the scaled error function complement.

The following equation defines the scaled error function complement.

© National Instruments 2971

 Functions

Inverse Error Function

Computes the inverse of the error function associated with a normal distribution.

This VI calculates the Error Function VI in reverse.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• inverf(x) —

inverf(x) returns the value of the inverse error function.

Inverse Error Function Complement

Computes the inverse of the complementary error function associated with a normal
distribution.

This VI calculates the Error Function Complement VI in reverse.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• inverfc(x) —

2972 ni.com
 Functions

inverfc(x) returns the value of the inverse error function complement.

Fresnel Integrals

Computes the Fresnel cosine and sine integral functions.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• C(x) —

C(x) returns the value of the Fresnel cosine integral.

• S(x) —

S(x) returns the value of the Fresnel sine integral.

The following equation defines the Fresnel cosine integral.

The following equation defines the Fresnel sine integral.

Dawson's Integral

Computes the Dawson integral.

© National Instruments 2973

 Functions

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• daw(x) —

daw(x) returns the value of the Dawson integral.

The following formula defines Dawson's integral function.

Elliptic & Parabolic Functions

Use this class of special functions to compute specific forms of elliptic integrals or
Weber functions.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Jacobian Elliptic Functions Determines the Jacobian elliptic functions cn, dn, and sn.

Parabolic Cylinder Function Computes the parabolic cylinder, or Weber, function.

2974 ni.com
 Functions

Jacobian Elliptic Functions

Determines the Jacobian elliptic functions cn, dn, and sn.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• k—

k is the integrand parameter.

• cn —

cn returns the value of the Jacobi elliptic function cn.

• dn —

dn returns the Jacobi elliptic function dn.

• sn —

sn returns the value of the Jacobi elliptic function sn.

• phi —

phi is the upper limit of the integral defining the function.

The following equations define the three Jacobian elliptic functions.

cn(x, k) = cos(ϕ) sn(x, k) = sin(ϕ)

where

© National Instruments 2975

 Functions

The function is defined according to the following intervals for the input values.

For any real value of integrand parameter k in the unit interval, the function is defined
for all real values of x.

Parabolic Cylinder Function

Computes the parabolic cylinder, or Weber, function.

Inputs/Outputs
• x—

x is the input argument. If x is negative, the VI uses the absolute value of x.

• v—

v specifies the order of the parabolic cylinder function.

• Dv(x) —

Dv(x) returns the value of the parabolic cylinder function.

The parabolic cylinder function, Dv(x), is a solution of the following differential

equation:

2976 ni.com
 Functions

Linear Algebra
Use the Linear Algebra VIs to perform matrix-related computations and analysis.

Note Many Linear Algebra VIs are available only in the LabVIEW Full and
Professional Development Systems. If you have the LabVIEW Base
Development System, you do not have the full set of the Linear Algebra VIs
described in this help file. A subset of the Linear Algebra VIs is available in the
LabVIEW Base Development System.

The VIs on this palette can return mathematics error codes.

Palette Object Description

Generates a special matrix based on matrix type. The data types you wire to the
Create Special
Input Vector2 and Input Vector1 inputs determine the polymorphic instance to
Matrix
use.

Create Real
Matrix From Generates a real matrix from Eigenvalues.
Eigenvalues

Use the Matrix functions to manipulate the elements, diagonals, and submatrices
Matrix of a matrix or 2D numeric array. Many of these functions complement existing
array operations but offer functionality for math algorithms based on matrices.

Solve Linear Solves a linear system AX = Y. The data types you wire to the Input Matrix and
Equations Known Vector inputs determine the polymorphic instance to use.

Computes the dot product of X Vector and Y Vector. The data types you wire to the
Dot Product
X Vector and Y Vector inputs determine the polymorphic instance to use.

© National Instruments 2977

 Functions

Palette Object Description

Computes the outer product of X Vector and Y Vector. The data types you wire to
Outer Product
the X Vector and Y Vector inputs determine the polymorphic instance to use.

Performs the multiplication of two input matrices or an input matrix and an input
AxB vector. The data types you wire to the A and B inputs determine the polymorphic
instance to use.

Kronecker Calculates the Kronecker product of the input matrices A and B. The data types
Product you wire to the A and B inputs determine the polymorphic instance to use.

Subspaces
Computes the angle between column spaces of two matrices.
Angle

Computes the determinant of Input Matrix. Wire data to the Input Matrix input to
Determinant
determine the polymorphic instance to use or manually select the instance.

Computes the norm of Input Vector. Wire data to the Input Vector input to
Vector Norm
determine the polymorphic instance to use or manually select the instance.

Computes the norm of Input Matrix. Wire data to the Input Matrix input to
Matrix Norm
determine the polymorphic instance to use or manually select the instance.

Computes the rank of Input Matrix. Wire data to the Input Matrix input to
Matrix Rank
determine the polymorphic instance to use or manually select the instance.

Finds the trace of Input Matrix. Wire data to the Input Matrix input to determine
Trace
the polymorphic instance to use or manually select the instance.

Test Matrix
Tests whether Input Matrix is a matrix of special type. Wire data to the Input
Type

2978 ni.com
 Functions

Palette Object Description

Matrix input to determine the polymorphic instance to use or manually select the
instance.

Matrix Computes the condition number of Input Matrix. Wire data to the Input Matrix
Condition input to determine the polymorphic instance to use or manually select the
Number instance.

Finds Inverse Matrix, if it exists, of Input Matrix. Wire data to the Input Matrix
Inverse Matrix input to determine the polymorphic instance to use or manually select the
instance.

Finds the PseudoInverse Matrix of Input Matrix. Wire data to the Input Matrix
PseudoInverse
input to determine the polymorphic instance to use or manually select the
Matrix
instance.

Transposes Input Matrix. If Input Matrix is a complex matrix, the VI performs

Transpose
conjugate transposition. Wire data to the Input Matrix input to determine the
Matrix
polymorphic instance to use or manually select the instance.

Matrix Square Computes the square root of Input Matrix. Wire data to the Input Matrix input to
Root determine the polymorphic instance to use or manually select the instance.

Computes the exponential of a square Input Matrix. Wire data to the Input Matrix
Matrix Exp input to determine the polymorphic instance to use or manually select the
instance.

Computes the nth power of Input Matrix. Wire data to the Input Matrix input to
Matrix Power
determine the polymorphic instance to use or manually select the instance.

© National Instruments 2979

 Functions

Palette Object Description

Computes the natural logarithm of a square Input Matrix. Wire data to the Input
Matrix
Matrix input to determine the polymorphic instance to use or manually select the
Logarithm
instance.

LU Performs the LU factorization of A so that PA = LU. Wire data to the A input to

Factorization determine the polymorphic instance to use or manually select the instance.

Performs Cholesky factorization on a symmetric or Hermitian positive definite

Cholesky
matrix. Wire data to the A input to determine the polymorphic instance to use or
Factorization
manually select the instance.

Cholesky Performs Cholesky factorization on the rank-1 updated Cholesky matrix. The VI
Factorization performs Cholesky factorization directly on the known factored matrix instead of
Rank-1 Update the updated matrix.

Performs the QR decomposition of A with or without column pivoting. Wire data to

QR
the A input to determine the polymorphic instance to use or manually select the
Decomposition
instance.

Computes the singular value decomposition (SVD) of the m × n matrix A. Wire data
SVD
to the A input to determine the polymorphic instance to use or manually select the
Decomposition
instance.

Generalized Computes the generalized singular value decomposition (GSVD) of a matrix pair
SVD (A,B). The data types you wire to the A and B inputs determine the polymorphic
Decomposition instance to use.

Performs the Schur decomposition of a square matrix. Wire data to the Input
Schur
Matrix input to determine the polymorphic instance to use or manually select the
Decomposition
instance.

2980 ni.com
 Functions

Palette Object Description

Performs the Hessenberg decomposition of Input Matrix. Wire data to the Input
Hessenberg
Matrix input to determine the polymorphic instance to use or manually select the
Decomposition
instance.

QZ Performs the QZ decomposition of a pair of square matrices. The data types you
Decomposition wire to the A and B inputs determine the polymorphic instance to use.

Sylvester Solves the Sylvester matrix equation. The data types you wire to the A, B, and C
Equations inputs determine the polymorphic instance to use.

Lyapunov Solves the Lyapunov matrix equation. The data types you wire to the A and B
Equations inputs determine the polymorphic instance to use.

Finds the eigenvalues and right eigenvectors of the square Input Matrix. Wire data
Eigenvalues
to the Input Matrix input to determine the polymorphic instance to use or
and Vectors
manually select the instance.

Generalized Computes the generalized right eigenvalues and eigenvectors of the matrix pair A
Eigenvalues and B. The data types you wire to the A and B inputs determine the polymorphic
and Vectors instance to use.

Balances the general matrix Input Matrix to improve the accuracy of computed
Matrix Balance eigenvalues and eigenvectors. Wire data to the Input Matrix input to determine
the polymorphic instance to use or manually select the instance.

Back Transforms the eigenvectors of a balanced matrix to those of the original matrix.
Transform Wire data to the Eigenvectors input to determine the polymorphic instance to use
Eigenvectors or manually select the instance.

© National Instruments 2981

 Functions

Palette Object Description

Matrix Computes the characteristic polynomial of Input Matrix. Wire data to the Input
Characteristic Matrix input to determine the polymorphic instance to use or manually select the
Polynomial instance.

Basic Linear
Use the Basic Linear Algebra Subroutines VIs to perform standard functions for
Algebra
basic vector and matrix operations.
Subroutines

Create Special Matrix

Generates a special matrix based on matrix type. The data types you wire to the Input
Vector2 and Input Vector1 inputs determine the polymorphic instance to use.

• Create Special Real Matrix VI

• Create Special Complex Matrix VI

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Linear Algebra\Matrix to a
Power.vi

Create Special Real Matrix VI

Generates a special matrix based on matrix type. The data types you wire to the Input
Vector2 and Input Vector1 inputs determine the polymorphic instance to use.

2982 ni.com
 Functions

Inputs/Outputs
• Input Vector2 —

Input Vector2 used as the input to construct a special matrix in some options.

• matrix type —

matrix type specifies the type of special matrix that this VI uses to generate as the Special Matrix
output.

Let n represent matrix size, X represent Input Vector1, nx represent the size of X, and Y
represent Input Vector2, ny represent the size of Y, and B represent the output Special Matrix.

0 Identity—Generates an n-by-n identity matrix.

Diagonal—Generates an nx-by-nx diagonal matrix whose diagonal elements are the
1
elements of X.
Toeplitz—Generates an nx-by-ny Toeplitz matrix, which has X as its first column and Y as its
2
first row. If the first element of X and Y are different, the first element of X is used.

Vandermonde—Generates an nx-by-nx Vandermonde matrix whose columns are powers of

the elements of X. The elements of a Vandermonde matrix are:

3
bi,j = xinx – j – 1

where i,j = 0…nx – 1.

Companion—Generates an nx-1-by-nx-1 companion matrix. If vector X is a vector of a

polynomial coefficient, the first element of X is the coefficient of the highest order, the last
element of X is the constant term in the polynomial, the corresponding companion matrix is
constructed as follows: the first row is
4

the rest of B from the second row is an identity matrix.

© National Instruments 2983

 Functions

The eigenvalues of a companion matrix contain the roots of the corresponding polynomial.

Hankel—Generates an nx-by-ny Hankel matrix, where X is the first column and Y is the last
5 row of the matrix. If the first element of Y and last element of X are different, this VI uses the
last element of X.
Hadamard—Generates an n-by-n Hadamard matrix, whose elements are 1 and –1. All
6 columns or rows are orthogonal to each other. matrix size must be a power of 2, a power of 2
multiplied by 12, or a power of 2 multiplied by 20. If n is 1, this VI returns an empty matrix.
7 Wilkinson—Generates an n-by-n Wilkinson matrix whose eigenvalues are ill-conditioned.

Hilbert—Generates an n-by-n Hilbert matrix, which has elements according to the following
equation.

where i,j = 0,1,…n – 1

9 Inverse Hilbert—Generates the inverse of an n-by-n Hilbert matrix.

10 Rosser—Generates an 8-by-8 Rosser matrix whose eigenvalues are ill-conditioned.

Pascal—Generates an n-by-n symmetric Pascal matrix, which has elements according to the
following equation.

11

where i,j = 0,1,…n – 1

• matrix size —

matrix size determines the dimension size of the output Special Matrix.

• Input Vector1 —

Input Vector1 used as the input to construct a special matrix in some options.

• Special Matrix —

Special Matrix is the generated matrix.

2984 ni.com
 Functions

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Linear Algebra\Matrix to a
Power.vi

Create Special Complex Matrix VI

Generates a special matrix based on matrix type. The data types you wire to the Input
Vector2 and Input Vector1 inputs determine the polymorphic instance to use.

Inputs/Outputs
• Input Vector2 —

Input Vector2 used as the input to construct a special matrix in some options.

• matrix type —

matrix type specifies the type of special matrix that this VI uses to generate as the Special Matrix
output.

Let n represent matrix size, X represent Input Vector1, nx represent the size of X, and Y
represent Input Vector2, ny represent the size of Y, and B represent the output Special Matrix.

0 Identity—Generates an n-by-n identity matrix.

1 Diagonal—Generates an nx-by-nx diagonal matrix whose diagonal elements are the

© National Instruments 2985

 Functions

elements of X.
Toeplitz—Generates an nx-by-ny Toeplitz matrix, which has X as its first column and Y as its
2
first row. If the first element of X and Y are different, the first element of X is used.

Vandermonde—Generates an nx-by-nx Vandermonde matrix whose columns are powers of

the elements of X. The elements of a Vandermonde matrix are:

3
bi,j = xinx – j – 1

where i,j = 0…nx – 1.

Companion—Generates an nx-1-by-nx-1 companion matrix. If vector X is a vector of a

polynomial coefficient, the first element of X is the coefficient of the highest order, the last
element of X is the constant term in the polynomial, the corresponding companion matrix is
constructed as follows: the first row is
4

the rest of B from the second row is an identity matrix.

The eigenvalues of a companion matrix contain the roots of the corresponding polynomial.

Hankel—Generates an nx-by-ny Hankel matrix, where X is the first column and Y is the last
5 row of the matrix. If the first element of Y and last element of X are different, this VI uses the
last element of X.
Hadamard—Generates an n-by-n Hadamard matrix, whose elements are 1 and –1. All
6 columns or rows are orthogonal to each other. matrix size must be a power of 2, a power of 2
multiplied by 12, or a power of 2 multiplied by 20. If n is 1, this VI returns an empty matrix.
7 Wilkinson—Generates an n-by-n Wilkinson matrix whose eigenvalues are ill-conditioned.

Hilbert—Generates an n-by-n Hilbert matrix, which has elements according to the following
equation.

where i,j = 0,1,…n – 1

9 Inverse Hilbert—Generates the inverse of an n-by-n Hilbert matrix.

2986 ni.com
 Functions

10 Rosser—Generates an 8-by-8 Rosser matrix whose eigenvalues are ill-conditioned.

Pascal—Generates an n-by-n symmetric Pascal matrix, which has elements according to the
following equation.

11

where i,j = 0,1,…n – 1

• matrix size —

matrix size determines the dimension size of the output Special Matrix.

• Input Vector1 —

Input Vector1 used as the input to construct a special matrix in some options.

• Special Matrix —

Special Matrix is the generated matrix.

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Linear Algebra\Matrix to a
Power.vi

Create Real Matrix From Eigenvalues

Generates a real matrix from Eigenvalues.

© National Instruments 2987

 Functions

Inputs/Outputs
• Eigenvalues —

Eigenvalues contains the eigenvalues from which you want to create Matrix. Eigenvalues must
be real or conjugate pairs.

• Matrix —

Matrix returns the real matrix whose eigenvalues are specified by Eigenvalues.

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

This VI generates the Matrix in the following form:

where n is the length of Eigenvalues and a0, a1, …, an – 1 are the coefficients of the
polynomial P(x).

The following equation defines P(x):

P(x) = (x – λ0)(x – λ1)···(x – λn – 1) = a0 + a1x + a2x² + … + an – 1xn – 1 + xn

where λ0, λ1, …, λn – 1 are the elements in Eigenvalues.

Solve Linear Equations

Solves a linear system AX = Y. The data types you wire to the Input Matrix and Known

2988 ni.com
 Functions

Vector inputs determine the polymorphic instance to use.

• Solve Linear Equations (single right hand) VI

• Solve Linear Equations (multiple right hand) VI
• Solve Complex Linear Equations (single right hand) VI
• Solve Complex Linear Equations (multiple right hand) VI

Let A be an m-by-n matrix that represents the Input Matrix, Y be the set of m
coefficients in Known Vector, and X be the set of n elements in Solution Vector that
solves the system

AX = Y

When m > n, the system has more equations than unknowns, so it is an over-
determined system. The solution that satisfies AX = Y might not exist, so the VI finds the
least-square solution X, which minimizes ||AX – Y||.

When m < n, the system has more unknowns than equations, so it is an under-
determined system. It may have infinite solutions that satisfy AX = Y. The VI finds one of
these solutions.

In the case of m = n, if A is a nonsingular matrix—no row or column is a linear

combination of any other row or column, respectively—then you can solve the system
for X by decomposing the input matrix A into its lower and upper triangular matrices, L
and U, such that

AX = LZ = Y

and

Z = UX

can be an alternate representation of the original system. Notice that Z is also an

n-element vector.

© National Instruments 2989

 Functions

Triangular systems are easy to solve using recursive techniques. Consequently, when
you obtain the L and U matrices from A, you can find Z from the LZ = Y system and X
from the UX = Z system.

In the case of m ≠ n, A can be decomposed to an orthogonal matrix Q and an upper

triangular matrix R, so that A = QR. The linear system then can be represented by QRX =
Y. You then can solve RX = QTY.

You can easily solve this triangular system to get x using recursive techniques.

Note You cannot always determine beforehand whether the matrix is

singular, especially with large systems. The Solve Linear Equations VI detects
singular matrices and returns an error, so you do not need to verify whether
you have a valid system before using this VI.

The numerical implementation of the matrix inversion is numerically intensive and,

because of its recursive nature, is also highly sensitive to round-off error introduced by
the floating-point numeric coprocessor. Although the computations use the maximum
possible accuracy, the VI cannot always solve the system.

Solve Complex Linear Equations

Let A represent the m-by-n Input Matrix, Y represent the set of m elements in the
Known Vector, and X represent the set of n elements in the Solution Vector that solves
for the system

AX = Y

When m > n, the system has more equations than unknowns, so it is an over-
determined system. Since the solution that satisfies AX = Y may not exist, the VI finds
the least-square solution X, which minimizes ||AX – Y||.

When m < n, the system has more unknowns than equations, so it is an under-
determined system. It might have infinite solutions that satisfy AX = Y. The VI then
selects one of these solutions.

2990 ni.com
 Functions

When m = n, if A is a nonsingular matrix—no row or column is a linear combination of

any other row or column, respectively—then you can solve the system for X by
decomposing the Input Matrix A into its lower and upper triangular matrices, L and U,
such that

AX = LZ = Y

and

Z = UX

can be an alternate representation of the original system. Notice that Z is also an

n-element vector.

Triangular systems are easy to solve using recursive techniques. Consequently, when
you obtain the L and U matrices from A, you can find Z from the LZ = Y system and X
from the UX = Z system.

When m ≠ n, A can be decomposed to an orthogonal matrix Q, and an upper triangular

matrix R, so that A = QR, and the linear system can be represented by QRX = Y. You then
can solve RX = QHY. You can easily solve this triangular system to get X using recursive
techniques.

Note The numerical implementation of the matrix inversion is numerically

intensive and, because of its recursive nature, is also highly sensitive to
round-off error introduced by the floating-point numeric coprocessor.
Although the computations use the maximum possible accuracy, the VI
cannot always solve for the system.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Linear Algebra\Linear
Algebra Calculator.vi

© National Instruments 2991

 Functions

Solve Linear Equations (single right hand) VI

Solves a linear system AX = Y. The data types you wire to the Input Matrix and Known
Vector inputs determine the polymorphic instance to use.

Inputs/Outputs
• Input Matrix —

Input Matrix is a square or rectangular, real matrix. The number of elements in the Known
Vector must be equal to the rows of the Input Matrix. If the number of elements in the Known
Vector does not match the rows of the Input Matrix, the VI sets the Solution Vector to an empty
array and returns an error.

When Input Matrix is singular, if the matrix type is General, the Solve Linear Equations VI finds
the least-square solution. Otherwise, the VI returns an error.

• Known Vector —

Known Vector is an array of known, dependent-variable values. The number of elements in the
Known Vector must be equal to the rows of the Input Matrix. If the number of elements in the
Known Vector does not match the rows of the Input Matrix, the VI sets the Solution Vector to an
empty array and returns an error.

• matrix type —

matrix type is the type of Input Matrix. Knowing the type of Input Matrix can speed up the
computation of the Solution Vector and can help you to avoid unnecessary computation, which
could introduce numerical inaccuracy.

General
0
(default)
1 Positive definite
2 Lower triangular
3 Upper triangular

• Solution Vector —

2992 ni.com
 Functions

Solution Vector is the solution X to AX = Y where A is the Input Matrix and Y is the Known Vector.

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

Let A be an m-by-n matrix that represents the Input Matrix, Y be the set of m
coefficients in Known Vector, and X be the set of n elements in Solution Vector that
solves the system

AX = Y

When m > n, the system has more equations than unknowns, so it is an over-
determined system. The solution that satisfies AX = Y might not exist, so the VI finds the
least-square solution X, which minimizes ||AX – Y||.

When m < n, the system has more unknowns than equations, so it is an under-
determined system. It may have infinite solutions that satisfy AX = Y. The VI finds one of
these solutions.

In the case of m = n, if A is a nonsingular matrix—no row or column is a linear

combination of any other row or column, respectively—then you can solve the system
for X by decomposing the input matrix A into its lower and upper triangular matrices, L
and U, such that

AX = LZ = Y

and

Z = UX

can be an alternate representation of the original system. Notice that Z is also an

n-element vector.

Triangular systems are easy to solve using recursive techniques. Consequently, when
you obtain the L and U matrices from A, you can find Z from the LZ = Y system and X

© National Instruments 2993

 Functions

from the UX = Z system.

In the case of m ≠ n, A can be decomposed to an orthogonal matrix Q and an upper

triangular matrix R, so that A = QR. The linear system then can be represented by QRX =
Y. You then can solve RX = QTY.

You can easily solve this triangular system to get x using recursive techniques.

Note You cannot always determine beforehand whether the matrix is

singular, especially with large systems. The Solve Linear Equations VI detects
singular matrices and returns an error, so you do not need to verify whether
you have a valid system before using this VI.

The numerical implementation of the matrix inversion is numerically intensive and,

because of its recursive nature, is also highly sensitive to round-off error introduced by
the floating-point numeric coprocessor. Although the computations use the maximum
possible accuracy, the VI cannot always solve the system.

Solve Complex Linear Equations

Let A represent the m-by-n Input Matrix, Y represent the set of m elements in the
Known Vector, and X represent the set of n elements in the Solution Vector that solves
for the system

AX = Y

When m > n, the system has more equations than unknowns, so it is an over-
determined system. Since the solution that satisfies AX = Y may not exist, the VI finds
the least-square solution X, which minimizes ||AX – Y||.

When m < n, the system has more unknowns than equations, so it is an under-
determined system. It might have infinite solutions that satisfy AX = Y. The VI then
selects one of these solutions.

When m = n, if A is a nonsingular matrix—no row or column is a linear combination of

any other row or column, respectively—then you can solve the system for X by

2994 ni.com
 Functions

decomposing the Input Matrix A into its lower and upper triangular matrices, L and U,
such that

AX = LZ = Y

and

Z = UX

can be an alternate representation of the original system. Notice that Z is also an

n-element vector.

Triangular systems are easy to solve using recursive techniques. Consequently, when
you obtain the L and U matrices from A, you can find Z from the LZ = Y system and X
from the UX = Z system.

When m ≠ n, A can be decomposed to an orthogonal matrix Q, and an upper triangular

matrix R, so that A = QR, and the linear system can be represented by QRX = Y. You then
can solve RX = QHY. You can easily solve this triangular system to get X using recursive
techniques.

Note The numerical implementation of the matrix inversion is numerically

intensive and, because of its recursive nature, is also highly sensitive to
round-off error introduced by the floating-point numeric coprocessor.
Although the computations use the maximum possible accuracy, the VI
cannot always solve for the system.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Linear Algebra\Linear
Algebra Calculator.vi

Solve Linear Equations (multiple right hand) VI

Solves a linear system AX = Y. The data types you wire to the Input Matrix and Known

© National Instruments 2995

 Functions

Vector inputs determine the polymorphic instance to use.

Inputs/Outputs
• Input Matrix —

Input Matrix is a square or rectangular, real matrix. The number of rows in the Known Matrix
must be equal to the rows of the Input Matrix. If the number of rows in the Known Matrix does
not match the rows of the Input Matrix, the VI sets the Solution Matrix to an empty matrix and
returns an error.

When Input Matrix is singular, if the matrix type is General, the VI finds the least-square solution.
Otherwise, the VI returns an error.

• Known Matrix —

Known Matrix is a matrix of known, dependent-variable values. Known Matrix must have the
same number of rows as Input Matrix. If the number of rows in Known Matrix and Input Matrix
are not equal, the VI sets Solution Matrix to an empty matrix and returns an error.

• matrix type —

matrix type is the type of Input Matrix. Knowing the type of Input Matrix can speed up the
computation of the Solution Matrix and can help you to avoid unnecessary computation, which
could introduce numerical inaccuracy.

General
0
(default)
1 Positive definite
2 Lower triangular
3 Upper triangular

• Solution Matrix —

Solution Matrix returns the solution X to AX = Y where A is the Input Matrix and Y is the Known
Matrix.

• error —

2996 ni.com
 Functions

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

Let A be an m-by-n matrix that represents the Input Matrix, Y be the set of m
coefficients in Known Vector, and X be the set of n elements in Solution Vector that
solves the system

AX = Y

When m > n, the system has more equations than unknowns, so it is an over-
determined system. The solution that satisfies AX = Y might not exist, so the VI finds the
least-square solution X, which minimizes ||AX – Y||.

When m < n, the system has more unknowns than equations, so it is an under-
determined system. It may have infinite solutions that satisfy AX = Y. The VI finds one of
these solutions.

In the case of m = n, if A is a nonsingular matrix—no row or column is a linear

combination of any other row or column, respectively—then you can solve the system
for X by decomposing the input matrix A into its lower and upper triangular matrices, L
and U, such that

AX = LZ = Y

and

Z = UX

can be an alternate representation of the original system. Notice that Z is also an

n-element vector.

Triangular systems are easy to solve using recursive techniques. Consequently, when
you obtain the L and U matrices from A, you can find Z from the LZ = Y system and X
from the UX = Z system.

In the case of m ≠ n, A can be decomposed to an orthogonal matrix Q and an upper

© National Instruments 2997

 Functions

triangular matrix R, so that A = QR. The linear system then can be represented by QRX =
Y. You then can solve RX = QTY.

You can easily solve this triangular system to get x using recursive techniques.

Note You cannot always determine beforehand whether the matrix is

singular, especially with large systems. The Solve Linear Equations VI detects
singular matrices and returns an error, so you do not need to verify whether
you have a valid system before using this VI.

The numerical implementation of the matrix inversion is numerically intensive and,

because of its recursive nature, is also highly sensitive to round-off error introduced by
the floating-point numeric coprocessor. Although the computations use the maximum
possible accuracy, the VI cannot always solve the system.

Solve Complex Linear Equations

Let A represent the m-by-n Input Matrix, Y represent the set of m elements in the
Known Vector, and X represent the set of n elements in the Solution Vector that solves
for the system

AX = Y

When m > n, the system has more equations than unknowns, so it is an over-
determined system. Since the solution that satisfies AX = Y may not exist, the VI finds
the least-square solution X, which minimizes ||AX – Y||.

When m < n, the system has more unknowns than equations, so it is an under-
determined system. It might have infinite solutions that satisfy AX = Y. The VI then
selects one of these solutions.

When m = n, if A is a nonsingular matrix—no row or column is a linear combination of

any other row or column, respectively—then you can solve the system for X by
decomposing the Input Matrix A into its lower and upper triangular matrices, L and U,
such that

2998 ni.com
 Functions

AX = LZ = Y

and

Z = UX

can be an alternate representation of the original system. Notice that Z is also an

n-element vector.

Triangular systems are easy to solve using recursive techniques. Consequently, when
you obtain the L and U matrices from A, you can find Z from the LZ = Y system and X
from the UX = Z system.

When m ≠ n, A can be decomposed to an orthogonal matrix Q, and an upper triangular

matrix R, so that A = QR, and the linear system can be represented by QRX = Y. You then
can solve RX = QHY. You can easily solve this triangular system to get X using recursive
techniques.

Note The numerical implementation of the matrix inversion is numerically

intensive and, because of its recursive nature, is also highly sensitive to
round-off error introduced by the floating-point numeric coprocessor.
Although the computations use the maximum possible accuracy, the VI
cannot always solve for the system.

Examples

Refer to the following example files included with LabVIEW.

• labview\examples\Mathematics\Linear Algebra\Linear
Algebra Calculator.vi

Solve Complex Linear Equations (single right hand) VI

Solves a linear system AX = Y. The data types you wire to the Input Matrix and Known
Vector inputs determine the polymorphic instance to use.

© National Instruments 2999

 Functions

Inputs/Outputs
• Input Matrix —

Input Matrix must be a nonsingular, square or rectangular, complex matrix. A nonsingular matrix
is a matrix in which no row or column contains a linear combination of any other row or column,
respectively. You cannot always determine beforehand whether the matrix is singular, especially
with large systems.

When Input Matrix is singular, if the matrix type is General, the VI finds the least-square solution.
Otherwise, the VI returns an error.

• Known Vector —

Known Vector is an array of known, dependent-variable values. The number of elements in

Known Vector must match the row size of the Input Matrix. If the number of elements in Known
Vector does not match the row size of Input Matrix, the VI sets Solution Vector to an empty array
and returns an error.

• matrix type —

matrix type is the type of Input Matrix. Knowing the type of Input Matrix can speed up the
computation of the Solution Vector and can help you to avoid unnecessary computation, which
could introduce numerical inaccuracy.

General
0
(default)
1 Positive definite
2 Lower triangular
3 Upper triangular

• Solution Vector —

Solution Vector is the solution X to AX = Y where A is the Input Matrix and Y is the Known Vector.

• error —

error returns any error or warning from the VI. You can wire error to the Error Cluster From Error
Code VI to convert the error code or warning into an error cluster.

3000 ni.com