User Subroutine Loading Rules

There are three distinctive phases regarding how MotionSolve loads usersub DLLs/SOs and functions.

They include:
  1. Resolve the usrsub_dll_name.
  2. Search and load the DLL.
  3. Load the subroutine (function) from the DLL.

Phase I: Resolve the DLL Name

The usrsub_dll_name can be explicitly specified as the element attribute in the XML file (element-level specification), as a command line option (model-level specification), or by the environment variable MS_USERSUBDLL (system/machine level specification).

If usrsub_dll_name is explicitly specified in the XML, (for example, usrsub_dll_name = "msautoutils" or usrsub_dll_name = "msautoutils.dll"), proceed to Phase II. Otherwise, if usrsub_dll_name is not defined in the XML (for example: usrsub_dll_name = "NULL"), check if the MotionSolve executable was invoked with an optional usrsub_dll_name. For example,
mbd_d input.xml output.mrf usrsub_dll_name
If the optional usrsub_dll_name is present in the command line, proceed to Phase II. Otherwise, if the optional usrsub_dll_name is absent in the command line as in,
mbd_d input.xml output.mrf

you can check if the environment variable MS_USERSUBDLL is defined or not. If it is, set usrsub_dll_name to what is defined in MS_USERSUBDLL. Otherwise, if MS_USERSUBDLL is not defined, MotionSolve displays an error.

Phase II: Search and Load the DLL

Using the usrsub_dll_name obtained from Phase I, MotionSolve first verifies if the usrsub_dll_name includes an absolute path (for example, usrsub_dll_name = "C:/mydll_dir/myusersub.dll"). In the case of the absolute path, MotionSolve attempts to load the DLL. If it loads successfully, proceed to Phase III. If if fails, MotionSolve displays an error.

If the DLL name is not an absolute path, then MotionSolve tries to do the following in sequence:
  1. Load it locally, relative to the directory of the XML file, then proceed to Phase III.
  2. If attempt 1 fails, MotionSolve looks in the NUSOL_DLL_DIR, the standard installation directory (for example <NUSOL_DLL_DIR>/dllname), and proceeds to Phase III.
  3. If attempt 2 fails, MotionSolve looks in MS_USERDLL_DIR.

Multiple paths can be specified in MS_USERDLL_DIR. For example, c:/mydll_dir1; e:/install/mydll_dir2; c:/mydll_dir3.

They are searched individually until the DLL is found and loaded. Once found, MotionSolve proceeds to Phase III. If all attempts fail and nothing is found, MotionSolve displays an error.

Phase III: Load the Subroutine (function) from the DLL

After the userdll is loaded in Phase II, MotionSolve checks if the usrsub_fnc_name is specified in the XML file. For example, 
usrsub_fnc_name = "var101"
If the usrsub_fnc_name is not specified in the XML file, for example:
usrsub_fnc_name = "NULL"

or the attribute is missing, then the usrsub_fnc_name is assigned a default name depending on the element type. For example, the usrsub_fnc_name for the Reference_Variable element is VARSUB.

After the usrsub_fnc_name is resolved, either by explicit name in the XML file or by default, MotionSolve loads the subroutine (function) from the DLL.