Master Shared Library Loading in Uniface 10.4

#architecture #softwaredevelopment #tutorial

Understanding how Uniface handles DLLs and Shared Objects is crucial for avoiding "File Not Found" errors and version conflicts.

If you have ever encountered a runtime error where a specific database connector or 3GL library refused to load, you were likely dealing with a search path issue. In Uniface 10.4, shared libraries are loaded in two distinct ways: Statically (at startup) and Dynamically (at runtime).

Here is a deep dive into how these mechanisms work and how to configure your environment variables correctly.

1. Static Loading (At Startup)

Static loading happens immediately when the Operating System (OS) starts the Uniface executable.

For example, when you launch Uniface, the OS sees that the executable is linked to the core library ucall. The OS loader must find and load this library before the application can even launch.

How the OS finds the files

Crucially, the executable does not contain the full path to the library (e.g., C:\Uniface\bin\ucall.dll). Instead, it only knows the base name. It relies entirely on the OS environment variables to find the file.

If your environment variable lists the directories in the wrong order, the OS might load an incompatible library from an older Uniface version installed on the same machine.

2. Dynamic Loading (At Runtime)

Dynamic loading occurs only when your code specifically requests a feature.

Connectors: Accessing an Oracle database triggers the loading of uora61.
3GL Code: Calling a function defined in the [USER_3GL] section of your assignment file triggers a load of that specific library.

Best Practice: Avoid hardcoding full paths in the [USER_3GL] section. Rely on the search path environment variables to maintain portability across different machines.

3. The Critical Environment Variables

The variable you need to configure depends entirely on your operating system. Ensure these are set in your shell or system properties before launching Uniface (often handled by the adm/insunis script on Unix/Linux).

Platform	Environment Variable
Windows	PATH
AIX	LIBPATH
Unix / Linux	LD_LIBRARY_PATH

Note: The iSeries (AS/400) uses a different mechanism entirely and does not use these variables.

4. Common Pitfalls & Troubleshooting

A classic mistake is having a mixed search path.

If you have Uniface 8.4 and 9.7 installed, and your PATH lists the 8.4 bin directory before the 9.7 directory, your 9.7 application might attempt to load 8.4 DLLs. This often results in obscure crashes or "entry point not found" errors.

Tools for Debugging

If you suspect a loading issue, don't guess—trace it.

On Windows:

The documentation historically references Filemon and Dependency Walker. However, for modern Windows debugging, you should use Process Monitor (ProcMon) from the Sysinternals Suite. It replaces Filemon and allows you to filter for "Load Image" events to see exactly which DLL is being grabbed from which path.

Legacy Tool: Dependency Walker (depends.exe) is still useful for static analysis, though modern rewrites like Dependencies (on GitHub) are often more stable for Windows 10/11.

On Unix/Linux:

Use the truss command (or strace on Linux) to trace system calls and see exactly where the OS is looking for your shared objects.

Summary

To ensure stability in your Uniface applications:

Check your Search Path: Ensure the bin (Windows) or lib (Unix) directory of your current Uniface version appears first.
Centralize Custom Libs: When creating your own shared libraries, place them in the standard Uniface bin or lib directory so they are found automatically without modifying the path.
Use Modern Tracing: Don't rely on trial and error; use Process Monitor or strace to verify which files are actually being loaded.