Uniface Deployment 101: Mastering $SEARCH_RESOURCES and Avoiding the "It Works in the IDE" Trap

Introduction

If you are migrating from older versions of Uniface (like 9.7) to Uniface 10, you might have stumbled upon the .asn (Assignment) file.

One setting in this file causes more confusion during deployment than any other: $SEARCH_RESOURCES.

In this post, we’ll demystify what this setting actually does, why Uniface 10 treats it differently than its predecessors, and how to configure it for a rock-solid deployment pipeline.

What is $SEARCH_RESOURCES?

In simple terms, $SEARCH_RESOURCES tells the Uniface Runtime (the kernel) where to look for the compiled objects (Forms, Services, Reports) it needs to execute.

There are generally two places Uniface can look for code:

• The Repository (DB): This is where your source code lives during development.
• UAR Files (Uniface Archive) or Directories: These are your compiled, portable application files.

The $SEARCH_RESOURCES setting defines whether the runtime should look at the source code in the database or strictly use the compiled archives.

The Configuration: resources_only

In the [SETTINGS] section of your assignment file, you will typically see this:

\[SETTINGS\]
$SEARCH\_RESOURCES = resources\_only

In Uniface 10, this is the standard for deployment.

• In the past (Uniface 9): You might have used resources_first or resources_last, which allowed the application to "fall back" to the database if a compiled file wasn't found.
• The Modern Way: resources_only forces the application to look exclusively in the files defined in the [RESOURCES] section. If a component isn't there, the application throws an error (usually -16 Component not found).

Why is this better?

1. Performance: Accessing a local file (or loading into memory via $MEMORY_ZIP) is significantly faster than querying a database for every component load.
2. Stability: You guarantee that what you tested is exactly what is running. No accidental "developer versions" sneaking in from a connected database.

The [RESOURCES] Section: First Match Wins

Once $SEARCH_RESOURCES is active, Uniface looks at the [RESOURCES] section to find the actual files. The most important rule here is sequence matters. Uniface scans this list from top to bottom and stops at the first match.

Here is a typical setup for a deployment environment:

[RESOURCES]
; 1. Hotfixes (Highest Priority)
.\\patches\\urgent_fix.uar

; 2. The Main Application
.\\bin\\my_erp_system.uar

; 3. Uniface System Libraries (Required)
usys:usys.uar
usys:usysicon.uar

The Scenario:

You have a bug in FRM_LOGIN.

1. You fix it and compile it into urgent_fix.uar.
2. You place this file in the patches folder.
3. Because urgent_fix.uar is listed before my_erp_system.uar, Uniface loads the new login form from the patch.
4. For all other components, it continues down the list to the main archive.

Common Pitfalls

Here are the "Gotchas" to watch out for when moving to a strict resources_only environment:

1. The "Shadowing" Problem

If you deploy a new my_erp_system.uar but forget to remove an old test_debug.uar that is listed higher up in the assignment file, Uniface will happily load the old code. It never warns you that duplicate objects exist.

2. Relative vs. Absolute Paths

Be careful with paths in your assignment file.

• .\bin\app.uar relies on the startup directory.
• If your shortcut starts in a different folder, the runtime won't find your resources.
• Tip: Use logical paths defined in [FILES] or absolute paths generated during your build process.

3. The "It Works in the IDE" Syndrome

The Uniface IDE usually connects to the Repository. If you forget to compile a specific Global Proc into your UAR, it will work fine on your machine (because the IDE sees the DB), but it will crash instantly in the Test environment where $SEARCH_RESOURCES = resources_only is active.

Summary

To ensure a smooth migration to Uniface 10:

1. Set $SEARCH_RESOURCES = resources_only in all non-development environments.
2. Treat your UAR files as immutable artifacts.
3. Keep your [RESOURCES] list clean and ordered.

Happy Coding!

---

Note: This article was created with the assistance of AI based on official Uniface 10.4 documentation to explain core security concepts and provide practical implementation details.