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


Index of functions

exit lv.cinversion lv.orI8 lv.subI32 lv.xorU32
wait lv.dump lv.orU16 lv.subI8
lv.addcleanup lv.exit lv.orU32 lv.substitute_separators
lv.addI16 lv.getyielding lv.orU8 lv.subU16
lv.addI32 lv.invert32 lv.pcall lv.subU32
lv.addI8 lv.invertI16 lv.print lv.subU8
lv.addU16 lv.invertI8 lv.setyielding lv.system_path
lv.addU32 lv.invertU16 lv.setyieldingdefaults lv.system_id
lv.addU8 lv.invertU32 lv.sethookcount lv.tickcount
lv.andI16 lv.invertU8 lv.shiftI16 lv.topath
lv.andI32 lv.isinf lv.shiftI32 lv.wait
lv.andI32 lv.isnan lv.shiftI8 lv.xorI8
lv.andI8 lv.luaversion lv.shiftU16 lv.xorI16
lv.andU16 lv.memusage lv.shiftU32 lv.xorI32
lv.andU8 lv.orI16 lv.shiftU8 lv.xorU8
lv.app_path lv.orI32 lv.subI16 lv.xorU16

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