LoadLibrary

LoadLibrary maps the specified executable module into the address space of the calling process.

Syntax

HINSTANCE LoadLibrary(
    LPCTSTR lpLibFileName
);

Parameters

LpLibFileName

Pointer to a null-terminated string that names the RTDLL module (a DLL file). The name specified is the filename of the module and is not related to the name stored in the library module itself, as specified by the library keyword in the module definition (DEF) file.

If the string specifies a path but the path does not exist in the specified directory, the function fails.

If the string does not specify a path but only a file name, it first checks the directory that the parent process that is loading the library resides in. Failing this, it then searches for files within the Search Path directories, as configured in the RTX64 Control Panel or Managed Code Framework.

Search executes in this order:

  1. The application directory of the current process.
  2. The directories in the Search Path, as configured in the RTX64 Control Panel (using the directory order specified in the search path).

The length of lpLibFileName should not be greater than MAX_PATH.

If no filename extension is specified in the lpLibFileName parameter, the default library extension .RTDLL is appended.

The .exe extension and DLL names without an extension (i.e., the trailing dot convention) are not supported.

NOTE: LoadLibrary does not support loading RTSS and RTDLL files that have pathnames containing Unicode characters with code points greater than 255. These characters include all Japanese, Chinese, Greek, Hebrew, Cyrillic, and Korean characters, as well as characters from many other non-Latin languages. This includes all ASCII and ISO Latin-1 characters, such as 'µ', 'ö', 'é', 'ß', 'ñ', 'ç', etc.

Return Value

A handle to the module if the function succeeds, NULL if the function fails

To get extended error information, call GetLastError.

License Failure Error Codes

LoadLibrary returns error codes upon license failure when a RTSS application is loaded, either by RTX64 Task Manager or RtssRun. The table below lists the possible error codes that can be returned, as well as their meanings.

NOTE: These error codes have been deprecated as of RTX64 3.0. For the complete list of new error codes, see RTX64 Error Codes.

Error Code Meaning
RTX64_NO_RUNTIME_LICENSE No Runtime license is available.
RTX64_EXPIRED_RUNTIME_LICENSE The Runtime license is expired.
RTX64_MODULE_NO_SDK_LICENSE An RTSS or RTDLL module being loaded (or an RTDLL on which it depends) was built without a valid SDK license.
RTX64_MODULE_EVAL_SDK_LICENSE An RTSS or RTDLL module being loaded (or an RTDLL on which it depends) was built with an evaluation SDK license, but the current Runtime license is a retail license.
RTX64_MODULE_LICENSE_INFO_MISSING An RTSS or RTDLL module being loaded (or an RTDLL on which it depends) is missing important license information. This typically means there is no "rtx64" data section in the module.
RTX64_MODULE_LICENSE_INFO_CORRUPT An RTSS or RTDLL module being loaded (or an RTDLL on which it depends) contains corrupted license information.
RTX64_MODULE_UNSUPPORTED_SDK

One or more object files in the RTSS or RTDLL module being loaded (or an RTDLL on which it depends) were built using an RTX64 SDK version that is incompatible with the current Runtime.
RTX64_CLOCK_REWIND

Clock rewind has been detected on the machine. This prevents our licensing from working correctly.

NOTE: RTSS/RTDLL applications will not run if the system clock on your machine is changed by more than 25 hours in either direction (backwards or forwards).

  • If resolution requires setting the system clock time backward, set the clock to the correct time, reboot the system, and wait 30 minutes.
  • If resolution requires setting the time forward, you must contact IntervalZero Support for assistance.

Remarks

LoadLibrary can be used to map an RTDLL module and return a handle that can be used in GetProcAddress to get the address of a RTDLL function.

If the module's RTDLL is not already mapped for the calling process, the system calls the RTDLL's DllMain function with the DLL_PROCESS_ATTACH value.

If the RTDLL's entry-point function does not return TRUE, LoadLibrary fails and returns NULL.

NOTE: It is not safe to call LoadLibrary from DllMain.

Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use, for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress.

Loaded Modules Maximum

The default maximum of loaded RTSS and RTDLL modules in a Real-time process is 64. If this number is exceeded, an error will appear advising that the number be increased. Follow the steps below to increase the maximum number of loaded RTSS and RTDLL modules.

To increase the maximum number of loaded modules:

  1. Open Registry Editor.
  2. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\RTX64\
  3. Do one of the following:
  4. Double-click MaxModules.
  5. Right-click MaxModules and then choose Modify.
  6. To increase the maximum number of loaded RTSS and RTDLL modules, increase the Value data value.
  7. Click OK.

Requirements

Minimum Supported Version

RTX64 2013

Search Path support was added in RTX64 2014 with Service Pack 2
Header windows.h
Library Rtx_Rtss.lib

See Also:

DllMain

GetProcAddress