Call-In Using the Call-In API

The Uniface 3GL Call-in API is a collection of call-in functions related to the ProcScript activate command.

Using this method, you can instantiate forms, services, and reports, and call operations in these instances, using return values and input/output parameters. The collection of available call-in functions is commonly referred to as the Call-in API.

The following is the typical sequence of statements to call a specific operation in a Uniface component:

#include <uactdef.h>

uecreate(...); /* Initialize the Uniface environment*/
ueopen(...); /* Get an environment handle*/
uinstnew(...); /* Create an instance of a component*/
uopract(...); /* Activate an operation in this component*/
uinstdel(...); /* Delete the component instance*/
uedelete(...); /* Close the Uniface environment*/

This might seem complicated, and we are not even using any parameters here. Fortunately, all of the code between uecreate and uedelete can be generated from the compiled signature information in the UAR file, by using the ide/sti command. This way you do not need to bother with all these API calls, and you can just activate the component as if it were a C function. For more information, see Using Call-In Stubs.

Note the following points about uecreate, ueopen, and uedelete:

Calling uecreate is necessary when the Uniface environment has not yet been started, which is typically the case when program execution starts within your own C code. In this case, you can use the environment handle returned by uecreate; you do not need to call ueopen. You must free the environment handle, after it has been shut down by uedelete, by calling ufreeh on it.
In contrast, suppose you have C code that is being called by Uniface using call-out, and that C code needs to call in to a Uniface component. In this case, there is already a Uniface environment, so it is not necessary—or even desirable—to call uecreate. Instead, you call ueopen to obtain the current Uniface environment handle. When you are finished with that handle, you must free it by calling ufreeh.
It is possible, and allowed, to call both uecreate and ueopen. This will typically happen if you use generated call-in stubs. Although these functions do not return the same value, they refer to the same handle internally; both handles are equally valid and can be used interchangeably. The handle returned by ueopen is an exact copy of the one returned by uecreate. The handle returned by ueopen should be freed after use by calling ufreeh on it.

Apart from the functions mentioned here, the Call-in API also provides functions to set and retrieve parameters of all types, to allocate Uniface memory, and to manage Uniface item lists. For more information, see APIs: 3GL Functions.

All functions in the call-in API are conveniently bundled in one shared library, ucall, and it is the only library you need to link if you are creating a call-in program.

For a working, ready-to-compile example of using the call-in API, see the example given with uecreate.