#DllLoad

Loads a DLL or EXE file before the script starts executing.

#DllLoad FileOrDirName

Parameters

FileOrDirName

Type: String

The path of a file or directory as explained below. This must not contain double quotes, wildcards or escape sequences other than semicolon (`;).

Built-in variables may be used by enclosing them in percent signs (for example, #DllLoad %A_ScriptDir%). Percent signs which are not part of a valid variable reference are interpreted literally. All built-in variables are valid, except for A_Args and built-in classes.

Known limitation: When compiling a script, variables are evaluated by the compiler and may differ from what the script would return when it is finally executed. The following variables are supported: A_AhkPath, A_AppData, A_AppDataCommon, A_ComputerName, A_ComSpec, A_Desktop, A_DesktopCommon, A_IsCompiled, A_LineFile, A_MyDocuments, A_ProgramFiles, A_Programs, A_ProgramsCommon, A_ScriptDir, A_ScriptFullPath, A_ScriptName, A_Space, A_StartMenu, A_StartMenuCommon, A_Startup, A_StartupCommon, A_Tab, A_Temp, A_UserName, A_WinDir.

File: The absolute or relative path to the DLL or EXE file to be loaded. If a relative path is specified, the directive searches for the file using the same search strategy as the system's function LoadLibraryW. Note: SetWorkingDir has no effect on #DllLoad because #DllLoad is processed before the script begins executing.

Directory: Specify a directory instead of a file to alter the search strategy by all subsequent occurrences of #DllLoad which do not specify an absolute path to a DLL or EXE. The new search strategy is the same as if Directory was passed to the system's function SetDllDirectoryW. If this parameter is omitted, the default search strategy is restored.

Note: This parameter is not an expression, but can be enclosed in quote marks (either 'single' or "double").

Remarks

Once a DLL or EXE has been loaded by this directive it cannot be unloaded by calling the system's function FreeLibrary. When the script is terminated, all loaded files are unloaded automatically.

The FileName parameter may optionally begin with *i and a single space, which causes the program to ignore any failure to load the file. This option should be used only if the script is capable of executing despite the failure, such as if the DLL or EXE is non-essential, or if the script is designed to detect the failure. For example:

#DllLoad "*i MyDLL"
if !DllCall("GetModuleHandle", "str", "MyDLL")
    MsgBox "Failed to load MyDLL!"

If the FileName parameter specifies a DLL name without a path and the file name extension is omitted, .dll is appended to the file name. To prevent this, include a trailing point character (.) in the file name.

Related

DllCall

Examples

#1

#DllLoad "%A_MyDocuments%\MyDLL.dll"