🚀 Deep Dive: The Uniface 3GL Call-In API & C Integration

Introduction

Integrating modern C/C++ applications with established Uniface systems doesn't have to be a black box.

The Uniface 3GL Call-In API acts as the bridge, mirroring the power of the ProcScript activate command but from within your C code.

This guide breaks down how to instantiate components and effectively manage the environment lifecycle using the ucall library.

The Core Mechanism

The Call-In API allows you to:

• Instantiate Uniface components (Forms, Services, Reports).
• Execute operations with full parameter support (IN/OUT).
• Control the Uniface environment (Start/Stop).

All necessary functions are bundled in the ucall shared library.

This is the single dependency you need to link against.

The Lifecycle: A "Typical" Sequence

The documentation often shows a sequence involving both creation and opening.

Here is what happens under the hood:

#include <uactdef.h>

// 1. Start Uniface (Only if not already running!)
uecreate(...); 

// 2. Get Handle (Optional if you have the handle from step 1)
ueopen(...); 

// 3. Component Lifecycle
uinstnew(...); // Create Instance
uopract(...);  // Activate Operation
uinstdel(...); // Delete Instance

// 4. Cleanup
uedelete(...); // Shutdown Environment

💡 Pro Tip: uecreate vs. ueopen

There is often confusion about when to use which.

Here is the rule of thumb:

Scenario A: You are the "Driver" (Call-In)

Your C program starts the process.

Uniface is not running.

Action: Call uecreate.

This starts the environment.

You can call ueopen afterwards (and generated stubs often do), but the handle from uecreate is already valid.

Cleanup: You must call ufreeh on your handle, and finally uedelete to shut down Uniface.

Scenario B: Uniface Called You (Call-Out)

Uniface is already running and called your C function.

Action: Do NOT call uecreate.

Instead, call ueopen to grab the existing environment handle.

Cleanup: You must still call ufreeh on the handle you got from ueopen when you are done, but do NOT call uedelete (you don't want to kill the parent Uniface process!).

The "Smart" Way: Generated Stubs

Writing the boilerplate above manually is error-prone.

Uniface allows you to generate wrapper code directly from your compiled UAR signatures.

Run the following command in your CLI:

ide /sti <your_component>

This generates C stubs that handle the messy uinstnew/uopract sequence for you, allowing you to call Uniface operations as if they were native C functions.

Conclusion

Whether you are manually managing handles for fine-grained control or using ide /sti for rapid development, the Call-In API is robust.

Just remember: always match your ueopen/uecreate calls with a corresponding ufreeh to prevent memory leaks.