Understanding $subsetreturn in Uniface 10.4 🚀

Note: This blog post was created with AI assistance. 🤖

If you're working with Uniface 10.4, you might have encountered situations where you need to retrieve specific data from your database. Today, we'll look at a powerful function called $subsetreturn that helps you work more efficiently with entity data.

What is $subsetreturn? 🤔

In simple terms, $subsetreturn is a function that returns only the most recently retrieved occurrences of an entity. Normally, when you work with entity parameters in Uniface operations, you get all occurrences. But sometimes, you only want the data you just fetched from the database.

Think of it like this: imagine you have a huge filing cabinet with customer records. Usually, when you ask for customer files, you get the entire drawer. But with $subsetreturn, you only get the specific files you just pulled out. 📁

When Should You Use It? 💡

$subsetreturn is especially useful when you're using the retrieve/a command. This command lets you retrieve multiple occurrences based on specific criteria. After retrieving these occurrences, $subsetreturn ensures that only these newly retrieved records are passed to your entity parameter.

Important: Any occurrences that were removed from the hitlist or deleted from the database will not be returned. This keeps your data clean and relevant. ✨

Where Can You Use It? 📍

You can use $subsetreturn in:

Form components
Report components
Service components

It must be used in an operation that has an entity parameter with direction OUT or INOUT.

A Practical Example 🎯

Let's say you want to retrieve all customers from the USA and return only those records. Here's how you would do it:

operation GET_USA_CUSTOMERS
params
    entity CUSTOMER : OUT
endparams
creocc "CUSTOMER", 0
retrieve/a "CUSTOMER"
set $subsetreturn
end ; GET_USA_CUSTOMERS

Let's break down what happens here:

Create operation: We define an operation called GET_USA_CUSTOMERS with an output parameter for the CUSTOMER entity.
Clear occurrences: The creocc command clears any existing customer occurrences.
Retrieve data: The retrieve/a command fetches customers based on your criteria (presumably USA customers through a retrieve profile).
Set subset return: The set $subsetreturn ensures only these newly retrieved USA customers are returned to the calling component.

How to Use It 🛠️

The syntax is straightforward:

set $subsetreturn(Entity)

You can also reset it when you're done:

reset $subsetreturn(Entity)

If you want to check how many occurrences will be returned, you can read the value:

NumOccurrences = $subsetreturn(Entity)

If $subsetreturn is not enabled, this will return 0.

Error Handling ⚠️

Like any good function, $subsetreturn provides error information through $procerror. Common errors include:

Invalid entity name: The entity you specified doesn't exist or isn't painted on the component.
Invalid parameter: The parameter name isn't valid or defined.