About LUA_PATH and LUA_CPATH

Lua offers a higher-level function to load and run libraries, called require. Require searches for the file in two different path variables: package.path and package.cpath. These path used by require are a little different from typical paths. Most programs use paths as a list of directories wherein to search for a given file. However, ANSI C (the abstract platform where Lua runs) does not have the concept of directories. Therefore, the path used by require is a list of patterns, each of them specifying an alternative way to transform a virtual file name (the argument to require) into a real file name. More specifically, each component in the path is a file name containing optional interrogation marks. For each component, require replaces each '?' by the virtual file name and checks whether there is a file with that name; if not, it goes to the next component. The components in a path are separated by semicolons (a character seldom used for file names in most operating systems). For instance, if the path is

package.path = ?;?.lua;c:\windows\?;/usr/local/lua/?/?.lua

then the call require("lili") will try to open the following files:

lili
lili.lua
c:\windows\lili
/usr/local/lua/lili/lili.lua

The only things that require fixes is the semicolon (as the component separator) and the interrogation mark; everything else (such as directory separators or file extensions) is defined in the path.

package.path is responsible for loading lua files. package.cpath is responsible for loading C libraries in binaries.

To use mlpi4Lua in your Lua runtime environment you have to ensure that the runtime finds the library. Simply add the path to mlpi4Lua/bin/... to package.cpath variable.

package.cpath = package.cpath .. ";" .. os.getenv("MLPI_SDK_01") .. "/mlpi4Lua/bin/win-any-x86/?51.dll"

For different Lua runtimes different mlpi libraries are provided:

Lua Runtime	Lua Version	package.cpath	Build against
JNLua 32 Bit	5.1	"/mlpi4Lua/bin/win-any-x86/?51.dll"	lua51.dll
JNLua 32 Bit	5.2	"/mlpi4Lua/bin/win-any-x86/?52.dll"	lua52.dll
Lua 32 Bit	5.3	"/mlpi4Lua/bin/win-any-x86/?53.dll"	lua53.dll
JNLua 64 Bit	5.1	"/mlpi4Lua/bin/win-any-x64/?51.dll"	lua51.dll
JNLua 64 Bit	5.2	"/mlpi4Lua/bin/win-any-x64/?52.dll"	lua52.dll
Lua 64 Bit	5.3	"/mlpi4Lua/bin/win-any-x64/?53.dll"	lua53.dll
LuaDist	5.1	"/mlpi4Lua/bin/win_luadist-any-x86/luadist?51.dll"	liblua.dll
XLC/MLC	5.3	build in	build in

On XLC/MLC target Lua runtime is provided as a firmware bundle. By default package.cpath includes all nessesary path information to find mlpi on target. So it is not necessary to modify package.cpath.

About return values

Every MLPI function call returns beside the return values of the function an integer which indicates if the function has succeeded(>=0) or not(<0) and a message representing human readable form of result. The return value is positive or zero if the call has succeeded and negative if the function call has failed. You may want to use either the mlpi.failed() or the mlpi.succeeded() function for quick evaluation of the return value.

Example: ...
require("mlpi")
local value, result, message = any mlpi call here...
if mlpi.failed(result) then
print("failed with " .. message)
else
print("SUCCESS")
end

In most cases, the return value not only holds information about success or failure, but also information about the cause of a failure. There is a list of definitions with some generic and most likely error codes.

Define	Value	Description
MLPI_S_OK	0x00360000	Return code "everything okay".
MLPI_E_FAIL	0xF0360001	General error during function call.
MLPI_E_NOTSUPPORTED	0xF0360002	The given function is not supported yet.
MLPI_E_INVALIDARG	0xF0360003	Invalid argument given to method.
MLPI_E_OUTOFMEMORY	0xF0360004	Out of memory.
MLPI_E_TIMEOUT	0xF0360005	Timeout during function call.
MLPI_E_SERVEREXCEPTION	0xF0360006	System exception on control side.
MLPI_E_CONNECTFAILED	0xF0360007	Connection failed.
MLPI_E_CREATEERROR	0xF0360008	Error creating the resource.
MLPI_E_SYSTEMERROR	0xF0360009	System error during execution.
MLPI_E_BUFFERTOOSHORT	0xF036000A	Given buffer is too short.
MLPI_E_INVALIDSIGNATURE	0xF036000B	Invalid signature.
MLPI_E_STARTERROR	0xF036000C	Error during start of functionality.
MLPI_E_WATCHDOGWARNING	0xF036000D	Watchdog warning occurred.
MLPI_E_WATCHDOGERROR	0xF536000E	Watchdog error occurred.
MLPI_E_UNIMPLEMENTED	0xF036000F	The given function is not implemented on this specific device.
MLPI_E_LIMIT_MIN	0xF0360010	The minimum of a limitation is exceeded.
MLPI_E_LIMIT_MAX	0xF0360011	The maximum of a limitation is exceeded.
MLPI_E_VERSION	0xF0360012	Version conflict.
MLPI_E_DEPRECATED	0xF0360013	Deprecated. The lib or function is no longer supported.
MLPI_E_PERMISSION	0xF0360014	Request declined due to missing permission rights.
MLPI_E_TYPE_MISSMATCH	0xF0360015	Type mismatch, present type doesn't match requested type.
MLPI_E_SIZE_MISSMATCH	0xF0360016	Size mismatch, present size doesn't match requested size.
MLPI_E_INVALID_HANDLE	0xF0360017	Invalid handle argument or NULL pointer argument.
MLPI_E_NOCONNECTION	0xF0360018	The connection is not established, no longer established or has been quit by peer.
MLPI_E_RD_WR_PROTECTION	0xF0360019	Request declined due to read or write protection.
MLPI_E_INVALID_FLOATINGPOINT	0xF036001A	Invalid floating point number given to method.
MLPI_E_NOTINITIALIZED	0xF036001B	Object not initialized yet.
MLPI_E_STREAM_OUT_OF_SYNC	0xF036001C	Send / Receive stream out of synchronization.
MLPI_E_INVALID_PRIVATEKEY_FILE	0xF036001D	SThe given private key file is broken or not existing.
MLPI_E_INVALID_CERTIFICATE_FILE	0xF036001E	The given certificate key file is broken or not existing.
MLPI_E_KEYPAIR_MISSMATCH	0xF036001F	The given certificate does not match the given private key.
MLPI_E_TLS_HANDSHAKE_FAILED	0xF0360020	The TLS handshake was not successful.
MLPI_E_GENERAL_AC_ERROR	0xF0360021	There was a general access control error.
MLPI_E_POLICY_VIOLATION_AC	0xF0360022	A violation occurred in the user and/or policies.
MLPI_E_USER_ALREADY_EXISTS	0xF0360023	The given username is already in use.
MLPI_E_GROUP_ALREADY_EXISTS	0xF0360024	The given groupname is already in use.
MLPI_E_MEMBERSHIP_ALREADY_EXISTS	0xF0360025	The given user is already member of the given group.
MLPI_E_USER_NOT_EXISTING	0xF0360026	The given user does not exist on the control.
MLPI_E_GROUP_NOT_EXISTING	0xF0360027	The given group does not exist on the control.
MLPI_E_MEMBERSHIP_NOT_EXISTING	0xF0360028	The given user is not member of the given group.

Please note that this is not a complete list of all possible return values a MLPI function might return. Besides these common error codes, there are also many device specific error codes. These error codes are specific to the facility (for example, Motion, Logic, sercos, drive...) of the connected device and not directly part of the MLPI. Still, all these error codes are unique and based on the idea that a failure message is a negative value (0xFxxxxxxx) and a success message is a positive value (0x0xxxxxxx). The difference to the errors listed above is that you won't find the description of the error code within this documentation, but within the documentation of the MLPI device you are connected to. For example, if you are connected to a XLC/MLC device, you will probably find more help on the error code by looking into the XLC/MLC diagnostics documentation which is not directly part of the MLPI SDK. In most cases, you will find the documentation included in an IndraWorks installation or you may want to download an up-to-date version from the http://www.boschrexroth.com homepage.

For the latest information, you should look at the BoschRexroth website. http://www.boschrexroth.com/oce