| LoadDLL | Function (tigcc.a)

dll.h

short LoadDLL (const char *VarName, unsigned long ID, unsigned short Major, unsigned short Minor);

Loads a DLL into memory and prepares it for use.

LoadDLL tries to load a DLL into memory and to prepare it for use. It traverses the complete VAT to find a fitting version of the DLL (so it is not necessary for the DLL to be in the same directory as the main program). The DLLName parameter is the standard ANSI C name of the DLL file which is to be loaded. The ID parameter is a DLL identification number introduced for safety reasons: any file which does not have the extension 'DLL', a valid embedded signature and an embedded identification number which is equal to ID is ignored (the identification number in the DLL itself is set using the DLL_ID entry in the DLL interface section). The parameters Major and Minor are the expected major and minor version numbers of the DLL (the actual major and minor version numbers in the DLL itself are set using the DLL_VERSION macro in the DLL interface section). LoadDLL will refuse to load a DLL if the expected and actual version numbers are not the same, or if the expected minor version number is greater than the actual minor version number. As LoadDLL searches trough all folders for a matching DLL, it is completely legal to have several DLLs with the same name (in different folders), but which differ in their ID numbers or version numbers. LoadDLL will load the first DLL found (if any) with a matching name, ID number and major version number, and whose minor version number is greater or equal to the expected minor version number.
LoadDLL returns one of the following values:

DLL_OK | The DLL was loaded and initialized successfully.
DLL_NOTINGHOSTSPACE | The DLL could not be loaded because the program counter is not in the "ghost space" (the virtual address space where HW2 protections do not take effect). Note that exe-packed programs are always executed in the ghost space; if you do not want to compress your program, you need to define `EXECUTE_IN_GHOST_SPACE`.
DLL_NOTFOUND | The DLL is not found. This means that either a file with the name DLLName is not found in any folder, or such files exist, but none of them has the correct extension ('DLL'), the correct embedded signature, and the correct identification number (determined by the ID parameter).
DLL_LOCKFAILED | The attempt to lock the DLL in memory has failed due to some strange reason. This error code is very unlikely.
DLL_OUTOFMEM | There is not memory to load the DLL into RAM.
DLL_ALREADYLOADED | There is already another DLL loaded in the RAM. Due to efficiency reasons, only one DLL is allowed to be loaded at the same time. You need to unload the current DLL using UnloadDLL before loading another one. Anyway, using more than one DLL is strongly deprecated if you don't know exactly what you are doing and why you are doing so.
DLL_WRONGVERSION | There is at least one valid DLL file with the name DLLName and with the correct extension, signature, and identification number, but none of them has a major version number which is equal to the expected major number (determined by the Major parameter) and a minor version number which is greater or equal than the expected minor number (determined by the Minor parameter).

Only if LoadDLL returns DLL_OK, it is valid to proceed further and to use functions imported from the DLL. No further checking is done by the functions from the DLL, so your program will definitely crash if you try to call any function from the DLL if LoadDLL has not returned DLL_OK. Also, don't forget to call UnloadDLL when the DLL is not needed any more (usually at the end of the program). So, any program which uses DLLs must have the following code fragment:

    if ((status = LoadDLL (DLLName, ID, Major, Minor)) != DLL_OK)
    {
      // Perform some kind of error processing
      // and terminate the program in some way
    }

    // Proceed further

    UnloadDLL ();

You may use LoadDLLThrow instead, which throws an error instead of returning an error code, but this means that you can not determine what caused the problem. As another solution, you may use ER_throw from error.h to throw your own error if loading the DLL fails.
Typically, if you use functions which may throw errors, you can either catch these errors using TRY...ONERR...ENDTRY blocks, or, if you want to pass them on to the AMS, you can use a single TRY...FINALLY...ENDFINAL block:

    if ((status = LoadDLL (DLLName, ID, Major, Minor)) != DLL_OK)
    {
      // Perform some kind of error processing
      // and terminate the program in some way
    }
    TRY

      // Proceed further

    FINALLY
      UnloadDLL ();
    ENDFINAL

Or, using LoadDLLThrow:

    LoadDLLThrow (DLLName, ID, Major, Minor);
    TRY

      // Proceed further

    FINALLY
      UnloadDLL ();
    ENDFINAL

Uses: HeapAllocPtr, HeapDeref, HeapGetLock, HeapLock, HeapUnlock, memcmp, strcmp, EX_patch, SymFindFirst, SymFindNext
Used by: LoadDLLThrow

See also: UnloadDLL, LoadDLLThrow, _DLL_call, _DLL_call_attr, _DLL_reference, _DLL_glbvar