What's the "handle" on Uniface Handles? 🤔 A Simple Guide

If you're working with #uniface, you've probably come across the handle data type. At first, it might seem a bit abstract. What is it? Why do we need it? Let's break it down in simple terms.

(Disclaimer: This post was created with the assistance of an AI to help explain the official Uniface documentation in simpler terms. All concepts are based on the Uniface 10.4 documentation.)

What Exactly is a handle? 🧐

Think of a handle as a reference or a pointer to something else in your application. It doesn't hold the object itself, but it holds the unique address of that object, allowing you to interact with it. It’s like having a remote control for your TV; the remote isn't the TV, but it lets you control it.

In Uniface, a handle can refer to one of the following:

• A component instance
• An entity within a component
• An occurrence (a specific record or row)
• A field in an occurrence
• An OCX object

How to Declare a handle ✍️

You can declare a handle in two main places in your ProcScript: in a variables block or a parameters block.

1. As a variable:

Inside a variables block, you can define a handle that you'll use within your component's script.

variables
  handle vMyComponentHandle
endvariables

2. As a parameter for an operation:

This is very common when you want one component to control or pass a reference to another.

operation doSomething
  params
    handle pComponentHandle : IN
  endparams

  ; ... your code here ...
end

Let's See an Example in Action! 🎬

The best way to understand is with a simple example. Imagine you have a component that needs to tell another component (let's call it a "Writer" component) to start writing a document. You can pass the handle of the Writer component to your current component.

operation exec
  params
    handle pWriter : IN 
  endparams

  ; Assign the incoming handle to a component variable
  $hWriter$ = pWriter 

  ; Use the handle to activate an operation on the other component
  $hWriter$->startdocument("true")

end; exec

What's happening here?

1. The exec operation receives a handle named pWriter as an input parameter.
2. This handle is stored in a component variable called $hWriter$.
3. Now, using the -> syntax, we can use our handle $hWriter$ to call the startdocument operation on the component that the handle points to. We've successfully controlled another component from a distance!

A Note on public vs. partner Handles 🕵️‍♀️

When you declare a handle variable, you can specify its scope as public or partner. This is a security feature.

• public handle: Can only access operations that are also declared as public on the target component.
• partner handle: Can access both public and partner operations. This gives it more privileges.

A Critical Word of Warning! ⚠️

The Uniface documentation gives a very important piece of advice: Do not convert a handle to a string and back.

Why? Because a handle is a live, managed reference. If you convert it to a string, you are just getting a text representation of its internal ID at that moment. It's no longer a functional pointer. Trying to convert that string back to a handle will not work and will likely cause errors. Always pass and store handles as the handle data type.

Happy coding! I hope this clears up the mystery of the Uniface handle.