DLL-related UNIFACE problems on Microsoft Windows platforms

This document describes the various problems that can occur with loading DLL's on Windows. It gives possible solutions as well as background information that helps you understand what is going on. Unless noted otherwise, the text applies to both Windows NT and Windows 95/98. Note that we do not cover Windows 3.11 and Windows 2000 in this document.

Whenever a DLL-related error code is displayed in the transcript window, this is a Windows errorcode, not a UNIFACE error code. Therefore, one should not try to look up this code in the UNIFACE Message Guide, because Windows and UNIFACE error codes are not the same. Doing so wil only lead to confusion. The most common Windows error codes will be described in this document. However, should you encounter some other error code you will need to look up that code somewhere, to understand what is going on. This will typically require that you have some developer software like Visual Studio or MDSN installed.

Other places where you can find windows error codes are:

The C header file "winerror.h" in your Visual Studio directory. Click here to see a local copy of that file.
The 'Error Lookup' program in Startup->Program Files->Microsoft Visual Studio->Microsoft Visual Studio Tools
The Microsoft Developer Network (MSDN)

Symptom:	Message in transcript window: Unable to locate 3GL function UDBXXX. where XXX is a 3-letter driver mnemonic, like ORA, SOL, MSS, etc.
Problem:	No entry point for the database driver XXX could be located. If no other messages were given, this almost certainly means you did not specify the DLL for this driver in your INI-file. If other message were also given just before this one, look at these messages first as they may well have be the cause of the problem.
Solution:	Make sure the relevant driver DLL is included in the [uniface_dlls] section of your usys.ini file. For example, if the message says Unable to locate 3GL function UDBSOL, check that you have the relevant Solid driver DLL included, e.g. [uniface_dlls] demandload=...,sol7222.dll Note that you can also include drivers in the [userdlls] section of the usys.ini file. But it is customary for UNIFACE DLL's to be loaded from the [uniface_dlls] section.
Background:	The most common DLL-related error in UNIFACE is probably this message in the transcript window: Unable to locate 3GL function UDBXXX. where XXX is a 3-letter driver mnemonic like SOL, ORA, or MSS. This may be confusing, as it seems to have something to do with user 3GL code. It doesn't ! The fact is that UNIFACE itself calls its drivers and other software modules in the same way as user 3GL, via a mechanism called "dispatch". The trick of dispatching is that UNIFACE can call an external routine by name rather than by its address. Explaining why this is necessary is somewhat beyond the scope of this document. Suffice to say that it is needed because of the dynamic configuration of UNIFACE, where it is not known at build time what pieces of software might be called. So when UNIFACE needs to call a driver, say ORA, it looks for the driver entrypoint UDBORA. If this is not already in memory, it will try to locate it in its list of "demandload" DLL's. The DLL's to be searched in this process are specified in the [uniface_dlls] and [userdlls] sections of your ini file. If none of these DLL's contain this entrypoint, UNIFACE will be unable to locate the 3GL function.

Symptom:	Message in transcript window: Unable to locate 3GL function UNETXXX. where XXX is a 3-letter driver mnemonic, like TCP, NMP, DNT, etc.
Problem:	No entry point for the network driver XXX could be located. If no other messages were given, this almost certainly means you did not specify the DLL for this driver in your INI-file. If other message were also given just before this one, look at these messages first as they may well have be the cause of the problem.
Solution:	Make sure the relevant driver DLL is included in the [uniface_dlls] section of your usys.ini file. For example, if the message mentioned the 3GL function UNETTCP, check that you have the TCP driver DLL included, e.g. [uniface_dlls] demandload=...,wsk1110c.dll Note that you can also include drivers in the [userdlls] section of the usys.ini file. But it is customary for UNIFACE DLL's to be loaded from the [uniface_dlls] section.
Background:	Technically, this is exactly the same issue as the one with the database drivers. See the explanation above.

Symptom:	Message in transcript window: Unable to locate: D:\UNIFACE\USYS7205\BIN\sol7222.dll
Problem:	The specified file could not be found. This would be a typical cause of an Unable to locate 3GL function UDBXXX message as described above. The mentioned DLL is one that UNIFACE attempts to load from either the [uniface_dlls] or the [userdlls] section of your usys.ini file. It may be that the pathname is misspelled, or the DLL was accidentally deleted or moved. Although not logical, this message could also mean that your DLL is damaged.
Solution:	Check the [uniface_dlls] and [userdlls] sections of your usys.ini file. The files mentioned in a demandload line are loaded from the usys\bin directory, unless this line was preceded by a path assignment (which is empty by default). For example, the above message could be caused by the following lines: [uniface_dlls] path=d:\uniface\usys7205\bin demandload=sol7222.dll,... In this case you need to check that the file does indeed exist in that location, that it is readable, and that it is a valid DLL file for your Windows operating system. To check whether the file is a valid DLL, you can click the right mouse button on it, and select the Quick View option. For a valid DLL, this will show a screen with this header: DYNAMIC LINK LIBRARY 32bit for Windows 95 and Windows NT If the Quick View screen shows binary information, the DLL has been corrupted, and needs to be restored from the distribution medium. If available, you can also choose the View Dependencies option in the right mouse button popup menu. In case of an invalid DLL, the Dependency Walker screen will show some message which clearly explains what the problem is.
Background:

Symptom:	Message in transcript window: Unable to load D:\UNIFACE\USYS7205\BIN\ora8040l.dll; error 1157
Problem:	The specified file could be located, but could not be loaded. This is another typical cause of an Unable to locate 3GL function UDBXXX message as described above. The mentioned DLL is one that UNIFACE attempts to load from either the [uniface_dlls] or the [userdlls] section of your usys.ini file. The reason that the DLL could not be loaded is most often that it needs to load other DLL's it depends on to do its work. For example, the Oracle driver will want to load a number of Oracle DLL's. If these cannot be found at load time, this will result in error 1157. The official Windows description of this errorcode is: ERROR_DLL_NOT_FOUND One of the library files needed to run this application cannot be found. This code is sometimes confused with the UNIFACE message with the same number, which says: 1157 - Could not get a COM CLSID for component <component name>. Signature not generated. Although this looks like it could be related to the problem, it isn't. As said before, error codes in this area are always Windows error codes, not UNIFACE codes.
Solution:	Unfortunately, neither UNIFACE nor Windows will tell you which DLL's could not be found. You will need to use some tool to find out. One possibility is to use a tool that traces the loading of DLL's or files. One such tool is NtFilmon, which is a shareware program that can be downloaded from www.sysinternals.com . This site has a large number of high-quality troubleshooting tools that will come in handy with problems like these. If you have Microsoft Visual Studio 6.0 installed, the easiest way however is to right-click on the offending DLL and choose the View Dependencies option, if you have that. If it's not in your menu, you may have to start this program from the Microsoft Visual Studio 6.0 Tools menu (the program is called Dependency Walker). The left upper part of the screen, shown here with all subtrees collapsed to save space, will reveal which libraries can not be located : In this case these were the libraries oci.dll and sqllib.dll. So you will have to make sure you have these DLL's in your search path. Note that these DLL's in turn may need other DLL's so this may be an iterative procedure. In this particular case it is clear that you should properly install the Oracle client software, instead of trying to patch up the installation. Note that this message does not always have to mean that the DLL's do not exist. In many cases, Windows uses the PATH environment variable to find additional DLL's, so it is worth checking if that variable contains the directories that contain your database-dependent DLL's. E.g., for the above case, a directory like d:\database\oracle\bin.
Background:	Most of the database driver DLL's shipped with UNIFACE are dependent on one or more DLL's provided by the database vendor. This dependency is compiled into the DLL (that is why you can see it with Dependency Walker). When Windows loads the driver DLL, it will also try to load these necessary DLL's. Typically, for this process to succeed, it is necessary that you have correctly installed the relevant DMBS software. Generally speaking, simply copying in the missing files from another location (yes, some people do this stuff...) is not to be advised.

Symptom:	Message in transcript window: Unable to load D:\UNIFACE\USYS7205\BIN\ora8040l.dll; error 126
Problem:	The specified file could be located, but could not be loaded. This essentially the same problem as error code 1157 described above. There does not seem to be any difference between the two situations, except that Windows NT reports error 126 and Windows 95/98 reports error 1157. We have not yet verified what Windows 2000 makes of this situation. The official Windows description of this error code is: ERROR_MOD_NOT_FOUND The specified module could not be found. Sometimes, but not always, this error is preceded by a Windows error box, saying that one or more DLL's could not be found in the search path. In many cases, Windows uses the PATH environment variable to find additional DLL's, so it is worth checking if that variable contains the directories that contain your database-dependent DLL's. On Windows NT, this is usually done when you install your database software, but it is worth checking out anyway. Example of a Windows error box on NT:
Solution:	See above.
Background:	See above.