Uniface Explained: What the Heck is an "Occurrence"? 🤔

Hey devs! 👋

If you've ever worked with Uniface, or are just diving into this powerful low-code platform, you've probably stumbled upon the term "Occurrence". It sounds a bit formal, but it's actually a super simple and fundamental concept. Let's break it down so you can code with more confidence! 🚀

What's an Entity? Let's Start There!

Before we talk about an occurrence, we need to know what an Entity is. Think of an entity in Uniface just like you'd think of a table in a SQL database. It's the blueprint for your data.

For example, you might have a CUSTOMER entity with fields like ID, NAME, and CITY. The entity itself doesn't hold any data; it just defines the structure. It’s like an empty spreadsheet with only column headers. 📝

Entity: CUSTOMER
Fields: ID, NAME, CITY

So, What's an Occurrence?

An occurrence is a single instance of an entity. In simple terms: it's one row of data. That’s it! ✨

If your CUSTOMER entity is the spreadsheet template, then each customer you add is a new occurrence.

Customer 1: (1, 'John Doe', 'New York') -> This is one occurrence.
Customer 2: (2, 'Jane Smith', 'London') -> This is another occurrence.
Customer 3: (3, 'Peter Jones', 'Berlin') -> And this is a third one!

So, an occurrence is basically a single record or a row that belongs to an entity. When you're working in a Uniface form and you see a grid of customers, each line you see is an occurrence. Simple, right? 😉

The "Current" Occurrence: Why It Matters

Here's where it gets practical. In your Uniface component (like a form or a service), Uniface always keeps track of a "current occurrence" for each entity. When you write ProcScript code like CUSTOMER.NAME = "New Name", you are changing the NAME field of whatever occurrence is currently active or in focus.

Imagine you have a list of customers on your screen. When you click on Jane Smith's row, that row becomes the current occurrence. Any code you run that modifies the CUSTOMER entity will now affect Jane's record. This is crucial for editing, deleting, or viewing details.

Common ProcScript Operations on Occurrences

You'll interact with occurrences all the time using ProcScript. Here are some of the greatest hits 🎶:

retrieve: Fetches occurrences from the database and loads them into your component.
creocc: Creates a new, empty occurrence, ready for you to fill with data. It’s like clicking an "Add New Row" button.
remocc: Marks the current occurrence for deletion. It doesn't delete it right away! The actual deletion happens when you store your changes. This is a safety net! 🥅
store: Saves all your changes (new, modified, and deleted occurrences) to the database.
lock: Puts a lock on the database row corresponding to the current occurrence, so no one else can edit it while you are. Very handy for preventing conflicts! 🤝

A Simple Example 💡

Let's say you're building a simple customer management form.

You use retrieve to load all customers into a grid. Each row is an occurrence of the CUSTOMER entity.
The user clicks on a customer named 'John Doe'. That occurrence is now the "current" one.
They change the city from 'New York' to 'Boston' in a form field. This updates the CITY field of the current occurrence in memory.
The user then clicks a "Delete" button which runs the remocc command. 'John Doe's' occurrence is now flagged for deletion. 🚩
Finally, they click "Save". Your code calls store, and Uniface sends the right SQL commands to the database to update the one record and delete the other. All done! 🎉

Common Pitfalls to Avoid 😵‍💫

Losing Track of the Current Occurrence: After a retrieve or a filter action, the current occurrence might reset to the first one in the list. If your code expects a specific occurrence to be active, you might end up modifying the wrong data! Always be mindful of what's current.
remocc Surprises: Remember, remocc just marks an occurrence. If your store fails for some reason (e.g., a database error), the occurrence will stick around. You need to handle the status codes ($status) to make sure everything went as planned.

Conclusion

And that's the magic of the "occurrence"! It's a fundamental building block in Uniface that represents a single record. Once you get the hang of thinking in terms of entities and their occurrences, you'll find that managing data in Uniface becomes incredibly logical and smooth.

Happy coding! 💻✨