Function documentation exported on 2015/09/23 15:06:55.21.

Index of functions

Background

The documentation of each function is headed by a synopsis that summarizes how the function can be called. Optional parameters are surrounded with square brackets. An arbitrary number of repeats, including zero repeats, of the preceding parameter is denoted by an ellipsis (three subsequent dots). As per the Lua calling conventions, the caller is not obliged to process all results.

Function documentation

exit

exit()
Exit without error. This interrupts script execution, calls any cleanup functions that were set via lv.cleanup, and brings the virtual machine instance on which the script executes to a halt.

Be wary of using this function. It makes for more readable code to let a script run to completion or to use the lua return or break statements. But when execution must be stopped from inside a function call, exiting offers an easy solution. Make sure that users of that function are aware that it might not return. If you want to exit while throwing an error, use the standard Lua error function instead.
Errors:
Cannot interrupt the virtual machine when called via a C function.
Calling exit inside a cleanup function makes no sense.
Cannot be called from a coroutine.
Not supported for a Lua for LabVIEW base state.
Up to function index

wait

wait(U32:millis)
Waits for the specified number of milliseconds before returning. This function uses the "Wait (ms)" node on the LabVIEW-side, which allows LabVIEW to do cooperative scheduling (this function is not a pure C-function).

Beware that, as opposed to the sleep() Lua for LabVIEW function, this function cannot be interrupted by a task wakeup occurrence. On returning from a wait, the auto-yielding timer is reset.
Parameters:
U32:millis, milliseconds to wait.
Errors:
Cannot interrupt the virtual machine when called via a C function.
Cannot be called from a coroutine.
Not supported for a Lua for LabVIEW base state.
Up to function index

lv.addcleanup

lv.addcleanup(func:cleanup)
Adds a cleanup function to the list of cleanups. When Lua execution encounters an error, completes, or is interrupted, the added cleanup functions are called in reverse order. This can be used to ensure the release of external resources managed by the script. Releasing resources in reverse order prevents resources that depend on previously allocated resources from causing trouble.

For technical reasons, cleanup functions must be Lua functions, though they may contain C and Lua for LabVIEW functions. They are not passed any arguments and any returned results are discarded. A convenient means of meeting these demands is to construct an anonymous function in-line with a call to this function. Example:

lv.addcleanup(function() release(resource) end)
Parameters:
func:cleanup, a Lua function that does some cleanup work.
Errors:
Cannot add a LabVIEW-side or C function.
Cannot be called from a coroutine.
Not supported for a Lua for LabVIEW base state.
Up to function index

lv.addI16

I16:sum=lv.addI16(I16:n1,I16:n2)
Add two numbers using signed 16 bit arithmetic.
Parameters:
I16:n1
I16:n2
Results:
I16:sum
Up to function index

lv.addI32

I32:sum=lv.addI32(I32:n1,I32:n2)
Add two numbers using signed 32 bit arithmetic.
Parameters:
I32:n1
I32:n2
Results:
I32:sum
Up to function index

lv.addI8

I8:sum=lv.addI8(I8:n1,I8:n2)
Add two numbers using signed 8 bit arithmetic.
Parameters:
I8:n1
I8:n2
Results:
I8:sum
Up to function index

lv.addU16

U16:sum=lv.addU16(U16:n1,U16:n2)
Add two numbers using unsigned 16 bit arithmetic.
Parameters:
U16:n1
U16:n2
Results:
U16:sum
Up to function index

lv.addU32

U32:sum=lv.addU32(U32:n1,U32:n2)
Add two numbers using unsigned 32 bit arithmetic.
Parameters:
U32:n1
U32:n2
Results:
U32:sum
Up to function index

lv.addU8

U8:sum=lv.addU8(U8:n1,U8:n2)
Add two numbers using unsigned 8 bit arithmetic.
Parameters:
U8:n1
U8:n2
Results:
U8:sum
Up to function index

lv.andI16

I16:and=lv.andI16(I16:n1,I16:n2)
Do a bit-wise AND of two signed 16 bit numbers.
Parameters:
I16:n1
I16:n2
Results:
I16:and
Up to function index

lv.andI32

I32:and=lv.andI32(I32:n1,I32:n2)
Do a bit-wise AND of two signed 32 bit numbers.
Parameters:
I32:n1
I32:n2
Results:
I32:and
Up to function index

lv.andI32

U32:and=lv.andI32(U32:n1,U32:n2)
Do a bit-wise AND of two unsigned 32 bit numbers.
Parameters:
U32:n1
U32:n2
Results:
U32:and
Up to function index

lv.andI8

I8:and=lv.andI8(I8:n1,I8:n2)
Do a bit-wise AND of two signed 8 bit numbers.
Parameters:
I8:n1
I8:n2
Results:
I8:and
Up to function index

lv.andU16

U16:and=lv.andU16(U16:n1,U16:n2)
Do a bit-wise AND of two unsigned 16 bit numbers.
Parameters:
U16:n1
U16:n2
Results:
U16:and
Up to function index

lv.andU8

U8:and=lv.andU8(U8:n1,U8:n2)
Do a bit-wise AND of two unsigned 8 bit numbers.
Parameters:
U8:n1
U8:n2
Results:
U8:and
Up to function index

lv.app_path

str:path=lv.app_path()
Return the path to the application directory.
Results:
str:path, application path.
Up to function index

lv.cinversion

str:version=lv.cinversion()
Returns a verbose description of the Lua for LabVIEW version.
Results:
str:version
Up to function index

lv.dump

str:text=lv.dump()
Dump the printed text present in the per Lua for LabVIEW state print buffer. See lv.print for details.
Results:
str:text
Up to function index

lv.exit

lv.exit()
Same as the exit function which was made a global to save some typing as it is a frequently used function.
Up to function index

lv.getyielding

U32:threshold,U32:time=lv.getyielding()
Gets the yielding threshold and time as set for the current virtual machine instance. Please refer to the documentation of lv.setyielding for details.
Results:
U32:threshold, milliseconds that must pass before another yield happens.
U32:time, milliseconds to remain yielded.
Errors:
Cannot be called from a coroutine.
Not supported for a Lua for LabVIEW base state.
Up to function index

lv.invert32

I32:n_inv=lv.invert32(I32:n)
Do a bit-wise inversion of a signed 32 bit number. This flips all bits.
Parameters:
I32:n
Results:
I32:n_inv
Up to function index

lv.invertI16

I16:n_inv=lv.invertI16(I16:n)
Do a bit-wise inversion of a signed 16 bit number. This flips all bits.
Parameters:
I16:n
Results:
I16:n_inv
Up to function index

lv.invertI8

I8:n_inv=lv.invertI8(I8:n)
Do a bit-wise inversion of a signed 8 bit number. This flips all bits.
Parameters:
I8:n
Results:
I8:n_inv
Up to function index

lv.invertU16

U16:n_inv=lv.invertU16(U16:n)
Do a bit-wise inversion of an unsigned 16 bit number. This flips all bits.
Parameters:
U16:n
Results:
U16:n_inv
Up to function index

lv.invertU32

U32:n_inv=lv.invertU32(U32:n)
Do a bit-wise inversion of an unsigned 32 bit number. This flips all bits.
Parameters:
U32:n
Results:
U32:n_inv
Up to function index

lv.invertU8

U8:n_inv=lv.invertU8(U8:n)
Do a bit-wise inversion of an unsigned 8 bit number. This flips all bits.
Parameters:
U8:n
Results:
U8:n_inv
Up to function index

lv.isinf

bool:infinite=lv.isinf(num:number)
Tests if a number is infinite, that is, an exceptional floating point number value as might result from dividing by zero. Example:

if (lv.isinf(n) and n<0) then print("minus infinity") end

To help you pass infinite values, Lua for LabVIEW defines an _Inf global. Simply negate it to obtain minus infinity.
Parameters:
num:number, number that might be infinite.
Results:
bool:infinite, true if infinite, false otherwise.
Up to function index

lv.isnan

bool:isit=lv.isnan(num:number)
Tests if a number is "not a number" (NaN), that is, an exceptional floating point number value as results from illegal operations such as tan(1/0). Sometimes, numbers that are NaN are used explicitly to mark that a value is invalid. To help you pass NaN values, Lua for LabVIEW defines a _NaN global.
Parameters:
num:number, number that might not be a number.
Results:
bool:isit, true if not a number, false otherwise.
Up to function index

lv.luaversion

str:version=lv.luaversion()
Returns a verbose description of the Lua version that has been linked into the Lua for LabVIEW shared library. Note that a brief Lua version string is stored in the _VERSION global.
Results:
str:version
Up to function index

lv.memusage

U32:usage=lv.memusage()
Returns the LabVIEW data space memory usage. This is not the sum total of memory in use by the LabVIEW process: the number excludes some runtime overhead, heap fragmentation holes, as well as memory in use by Lua. By comparing successive usage values, allocation overhead and memory leaks can be determined. Note that LabVIEW does not immediately deallocate memory that is no longer in use. This holds in particular for data passed to subVIs on prior calls. Consequently a short-term rise in memory usage is no proof of a leak.

Beware: this function erroneously returns zero when used under LabVIEW 7.0 for Mac OS X. This is a Mac-specific LabVIEW bug: VI.lib/Platform/system.llb/Memstats.vi does not work either.
Results:
U32:usage, in bytes.
Up to function index

lv.orI16

I16:or=lv.orI16(I16:n1,I16:n2)
Do a bit-wise OR of two signed 16 bit numbers.
Parameters:
I16:n1
I16:n2
Results:
I16:or
Up to function index

lv.orI32

I32:or=lv.orI32(I32:n1,I32:n2)
Do a bit-wise OR of two signed 32 bit numbers.
Parameters:
I32:n1
I32:n2
Results:
I32:or
Up to function index

lv.orI8

I8:or=lv.orI8(I8:n1,I8:n2)
Do a bit-wise OR of two signed 8 bit numbers.
Parameters:
I8:n1
I8:n2
Results:
I8:or
Up to function index

lv.orU16

U16:or=lv.orU16(U16:n1,U16:n2)
Do a bit-wise OR of two unsigned 16 bit numbers.
Parameters:
U16:n1
U16:n2
Results:
U16:or
Up to function index

lv.orU32

U32:or=lv.orU32(U32:n1,U32:n2)
Do a bit-wise OR of two unsigned 32 bit numbers.
Parameters:
U32:n1
U32:n2
Results:
U32:or
Up to function index

lv.orU8

U8:or=lv.orU8(U8:n1,U8:n2)
Do a bit-wise OR of two unsigned 8 bit numbers.
Parameters:
U8:n1
U8:n2
Results:
U8:or
Up to function index

lv.pcall

bool:success,[any:res],...=lv.pcall(func:lvfunc,[any:arg],...)
Performs a protected call on a Lua for LabVIEW function. For technical reasons, the Lua base library function pcall cannot protect functions that call into LabVIEW. To still be able to catch errors thrown on the LabVIEW side this function has been provided. Note that it only works when used to directly call a Lua for LabVIEW function. Lua functions that in turn call Lua for LabVIEW functions cannot be protected.
Parameters:
func:lvfunc, the Lua for LabVIEW function to perform a protected call on.
[any:arg], argument to pass to the Lua for LabVIEW function.
...
Results:
bool:success, true when the call did not throw an error.
[any:res], error message or result returned by the Lua for LabVIEW function.
...
Errors:
A Lua or C function is not an allowed argument.
Cannot be called from a coroutine.
Not supported for a Lua for LabVIEW base state.
Up to function index

lv.print

lv.print([any:arg],...)
Print to a per-Lua for LabVIEW-state print buffer. Display of the print buffer must be separately arranged for: this function is independent of any display update and therefore operates with little overhead. This function complements print. Use the lv.dump function or the Poll Print Buffer API VI to retrieve the printed text for display. The "Task Manager" can open a print console that displays the print buffer of a task.

The provided arguments are converted to printable strings that are concatenated with spaces inserted between strings and a linefeed appended to the end. The result is appended to the print buffer. The print buffer is a circular buffer with a capacity of 32768 (2^15) characters: when more than this number of characters is printed to the buffer, only the most recent text is retained.
Parameters:
[any:arg], argument to be printed.
...
Up to function index

lv.setyielding

lv.setyielding(U32:threshold,U32:time)
Sets the yielding threshold and time for the current virtual machine instance provided that it was not opened as a base state (which cannot be interrupted nor call LabVIEW). This allow further tuning of the scheduling of the virtual machine beyond the execution system and priority settings offered by LabVIEW. Such tuning can help in case of scripts that perform protracted operations. Scripts that perform brief, periodic or event driven actions without polling will not be affected by the yielding settings.

Lua for LabVIEW implements automatic yielding of the virtual machine so as to assist with cooperative multitasking. This is essential for proper multitasking when the LabVIEW runtime runs in single-threading mode, and also allows some tuning of the CPU usage of a script. The virtual machine frequently checks how many milliseconds have passed since the last yield, wait, or re-entrant Lua for LabVIEW function returned. If this value is equal to or larger than the set threshold, another yield will be performed. On a yield, the virtual machine is interrupted and a wait will be performed on the LabVIEW side that lasts the set yield time. Roughly, this allows LabVIEW to schedule other pending work, but the precise scheduling behaviour will vary depending on the threading mode, operating system, CPU load, and LabVIEW version. Refer to the LabVIEW documentation or perform some latency tests to learn more. Beware that the update resolution of the LabVIEW millisecond counter, which is used to time the yields, can be worse than one millisecond on certain OS platforms.

Typically, a yield time of zero will be specified so that the virtual machine will resume immediately if there is no other pending work. Note though that for LabVIEW 7.0 and 6.x in multi-threading mode, pending work in a different execution system does not get scheduled because of a wait(0). To limit the CPU usage of your script, or to allow better opportunities for multi-threaded scheduling, a non-zero yield time can be specified. Beware though that if there is pending work in the same execution system that takes up all of the yield time, there will still be no forced switch to work pending for other execution systems.

To disable auto yielding, use a threshold of zero. This might be useful for obtaining more consistent loop timings. Note though that in the absence of auto-yielding, the script will need to frequently wait at or call into the LabVIEW side unless it is allowed to hog a thread.

The yields only interrupt virtual machine operations and not LabVIEW-side or C-side operations. Thus, scripts that spend most of their time inside LabVIEW-side or C functions cannot be accurately tuned. Note though that the scheduler will likely have plenty of other opportunities for cooperative scheduling while on the LabVIEW-side.
Parameters:
U32:threshold, milliseconds that must pass before another yield happens. When zero, yielding is disabled.
U32:time, milliseconds to remain yielded.
Errors:
Cannot be called from a coroutine.
Not supported for a Lua for LabVIEW base state.
Up to function index

lv.setyieldingdefaults

lv.setyieldingdefaults(U32:threshold,U32:time)
Set the default values for the yielding threshold and time so as to globally tune the multitasking behaviour of Lua for LabVIEW. Each new virtual machine instance will use the newly set defaults. The default values for the yielding defaults are a threshold of 2 milliseconds and a yielding time of 0 milliseconds. This function is typically called as part of a bootstrap script that prepares for the running of further scripts. Please refer to the documentation of lv.setyielding for details on the auto-yielding mechanism.
Parameters:
U32:threshold, new millisecond value for the default yielding threshold.
U32:time, new millisecond value for the default yielding time.
Up to function index

lv.sethookcount

lv.sethookcount(I32:count)
Sets the opcode count for the current virtual machine instance provided that it was not opened as a base state (which cannot be interrupted nor call LabVIEW).
This value determines after how many opcodes the Lua virtual machine should yield to pass control back to LabVIEW. The default of 50 should only be lowered for special circumstances such as when implementing some sort of debugging in the Lua script itself. For normal operation, lowering this will cause significant slowdown of the Lua code execution.
Parameters:
I32:count, new opcode yield count to use.
Up to function index

lv.shiftI16

I16:shifted=lv.shiftI16(I16:n,I32:p)
Shift a signed 16 bit number left or right by a given number of bit positions. Beware that the sign gets extended when shifting to the right.
Parameters:
I16:n, the number holding the bit pattern to shift.
I32:p, the number of bit positions to shift by, to the left if positive, to the right if negative.
Results:
I16:shifted
Up to function index

lv.shiftI32

I32:shifted=lv.shiftI32(I32:n,I32:p)
Shift a signed 32 bit number left or right by a given number of bit positions. Beware that the sign gets extended when shifting to the right.
Parameters:
I32:n, the number holding the bit pattern to shift.
I32:p, the number of bit positions to shift by, to the left if positive, to the right if negative.
Results:
I32:shifted
Up to function index

lv.shiftI8

I8:shifted=lv.shiftI8(I8:n,I32:p)
Shift a signed 8 bit number left or right by a given number of bit positions. Beware that the sign gets extended when shifting to the right.
Parameters:
I8:n, the number holding the bit pattern to shift.
I32:p, the number of bit positions to shift by, to the left if positive, to the right if negative.
Results:
I8:shifted
Up to function index

lv.shiftU16

U16:shifted=lv.shiftU16(U16:n,I32:p)
Shift an unsigned 16 bit number left or right by a given number of bit positions.
Parameters:
U16:n, the number holding the bit pattern to shift.
I32:p, the number of bit positions to shift by, to the left if positive, to the right if negative.
Results:
U16:shifted
Up to function index

lv.shiftU32

U32:shifted=lv.shiftU32(U32:n,I32:p)
Shift an unsigned 32 bit number left or right by a given number of bit positions.
Parameters:
U32:n, the number holding the bit pattern to shift.
I32:p, the number of bit positions to shift by, to the left if positive, to the right if negative.
Results:
U32:shifted
Up to function index

lv.shiftU8

U8:shifted=lv.shiftU8(U8:n,I32:p)
Shift an unsigned 8 bit number left or right by a given number of bit positions.
Parameters:
U8:n, the number holding the bit pattern to shift.
I32:p, the number of bit positions to shift by, to the left if positive, to the right if negative.
Results:
U8:shifted
Up to function index

lv.subI16

I16:difference=lv.subI16(I16:n1,I16:n2)
Subtract two numbers using signed 16 bit arithmetic.
Parameters:
I16:n1
I16:n2
Results:
I16:difference
Up to function index

lv.subI32

I32:difference=lv.subI32(I32:n1,I32:n2)
Subtract two numbers using signed 32 bit arithmetic.
Parameters:
I32:n1
I32:n2
Results:
I32:difference
Up to function index

lv.subI8

I8:difference=lv.subI8(I8:n1,I8:n2)
Subtract two numbers using signed 8 bit arithmetic.
Parameters:
I8:n1
I8:n2
Results:
I8:difference
Up to function index

lv.substitute_separators

bool:prior=lv.substitute_separators(bool:enable)
Enable/disable path separator substitution. When enabled, a Lua string about to be converted to a LabVIEW path will first have all occurrences of both "\" and "/" replaced with the platform-specific path separator. This will make path strings that use either type of separator work on multiple platforms.

By default, separator substitution is enabled. If you do not care for platform independence you might wish to disable this feature since, rarely, "\" or "/" are used as part of directory or filenames on platforms where either character does not serve as a separator.

To disable substitution, call this function when your application initialises, preferably before any paths are used. This can be done as part of a bootstrap script. For more information refer to the path data type documentation.
Parameters:
bool:enable, true to enable, false to disable.
Results:
bool:prior, prior setting.
Up to function index

lv.subU16

U16:difference=lv.subU16(U16:n1,U16:n2)
Subtract two numbers using unsigned 16 bit arithmetic.
Parameters:
U16:n1
U16:n2
Results:
U16:difference
Up to function index

lv.subU32

U32:difference=lv.subU32(U32:n1,U32:n2)
Subtract two numbers using unsigned 32 bit arithmetic.
Parameters:
U32:n1
U32:n2
Results:
U32:difference
Up to function index

lv.subU8

U8:difference=lv.subU8(U8:n1,U8:n2)
Subtract two numbers using unsigned 8 bit arithmetic.
Parameters:
U8:n1
U8:n2
Results:
U8:difference
Up to function index

lv.system_path

str:path=lv.system_dir([int:type, [bool:create]])
Return the path to any of the well known common platform paths.
Parameters:
[int:type], the type of path to retrieve.

no parameter: return the application directory.
0: user home
1: user desktop
2: user documents
3: user application data
4: user preferences
5: user temporary
6: public documents
7: public application data
8: public preferences
9: public cache
10: system core libraries
11: system installed libraries
12: application files
13: boot volume root

[bool:create], if set true function should attempt to create the path if it does not exist.
Results:
str:path, application path. Up to function index

lv.system_id

str:identifier=lv.system_id([int:type]])
Return the system identifier for the current platform.
Parameters:
[int:type], the type of path to retrieve

0: device name (default)
1: device serial number
2: device comment
3: primary MAC address
4: primary IP address

Results:
str:identifier
Up to function index

lv.tickcount

U32:ms_count=lv.tickcount()
Reads the current value of the LabVIEW millisecond counter, which is an unsigned 32 bit value. Note that the counter overflows when it reaches 2^32. Thus, to properly determine the time difference between subsequent counter reads, the read values must be subtracted using unsigned 32 bit arithmetic, e.g. using lv.subU32. Beware that this works only for time differences up to 2^32-1 milliseconds. The update resolution of the counter can vary between OS platforms.
Results:
U32:ms_count, current value of the millisecond counter.
Up to function index

lv.topath

str:path=lv.topath(str:path)
Convert a path to a platform-specific non-redundant path. This function converts a string to a LabVIEW path and back to a string. This will cause the equivalence-preserving modifications made on converting a string to a path to be applied, if any. In particular, "\" and "/" will have been replaced with the platform-specific path separator, if so configured, and any occurrences of "." and ".." will be contracted in the usual "String to Path" manner.
Parameters:
str:path, path to platform.
Results:
str:path, platformed path.
Up to function index

lv.wait

lv.wait()
Same as the wait function which was made a global to save some typing as it is a frequently used function.
Up to function index

lv.xorI16

I16:xor=lv.xorI16(I16:n1,I16:n2)
Do a bit-wise exclusive OR of two signed 16 bit numbers.
Parameters:
I16:n1
I16:n2
Results:
I16:xor
Up to function index

lv.xorI32

I32:xor=lv.xorI32(I32:n1,I32:n2)
Do a bit-wise exclusive OR of two signed 32 bit numbers.
Parameters:
I32:n1
I32:n2
Results:
I32:xor
Up to function index

lv.xorI8

I8:xor=lv.xorI8(I8:n1,I8:n2)
Do a bit-wise exclusive OR of two signed 8 bit numbers.
Parameters:
I8:n1
I8:n2
Results:
I8:xor
Up to function index

lv.xorU16

U16:xor=lv.xorU16(U16:n1,U16:n2)
Do a bit-wise exclusive OR of two unsigned 16 bit numbers.
Parameters:
U16:n1
U16:n2
Results:
U16:xor
Up to function index

lv.xorU32

U32:xor=lv.xorU32(U32:n1,U32:n2)
Do a bit-wise exclusive OR of two unsigned 32 bit numbers.
Parameters:
U32:n1
U32:n2
Results:
U32:xor
Up to function index

lv.xorU8

U8:xor=lv.xorU8(U8:n1,U8:n2)
Do a bit-wise exclusive OR of two unsigned 8 bit numbers.
Parameters:
U8:n1
U8:n2
Results:
U8:xor
Up to function index