Demystifying Uniface ProcScript: A Simple Guide to $totdbocc 🚀

Hello, fellow developers! 👨‍💻 If you're working with Uniface, you know it has its own unique way of doing things. Today, let's dive into a small but very useful ProcScript function: $totdbocc. It might seem simple, but understanding it correctly can save you a lot of headaches.

A quick note: This article was outlined and written with the help of an AI to make the documentation as clear and simple as possible.

What Exactly is $totdbocc? 🤔

In simple terms, $totdbocc is a counter. It tells you the total number of occurrences (think of them as rows or records) for a specific entity that have been fetched from the database and are currently loaded into your component's memory.

You can use it in two ways:

• $totdbocc: This gets the count for the current entity your cursor is on.
• $totdbocc("MY_ENTITY"): This gets the count for a specific entity you name.

If something goes wrong (for example, you use an entity name that doesn't exist), it returns an empty string, and you can check the $procerror function to see what happened.

The Key Difference: $totdbocc vs. $totocc vs. $hits

This is where many developers get confused. It's important to know the difference between these three functions:

• ✅ $totdbocc: Counts only the records that have been fetched from the database into the component.
• ✅ $totocc: Counts all records currently in the component. This includes both the records you fetched from the database AND any new records the user has created but not yet saved.
• ✅ $hits: Counts the total number of records in the database that match your query criteria, even if you haven't loaded them all into your component yet.

A Practical Example: Finding Unsaved Records 💡

Let's look at a real-world scenario. Imagine you have a form where a user can add new customers. You want to show a message telling them how many new customers they've added before they save. This is a perfect job for $totdbocc!

Here is the code from the Uniface documentation:

trigger detail
  if ($totocc > $totdbocc)
    $1 = ($totocc - $totdbocc)
    message "%%$1 customer(s) have been added"
  endif
end; detail

How it works:

1. The code checks if $totocc (all records in the form) is greater than $totdbocc (only records from the database).
2. If it is, we know the user has created new records because the total count is higher than what we originally loaded.
3. We then calculate the difference to find out exactly how many new records were added.
4. Finally, a message is shown to the user, like "2 customer(s) have been added".

When Does the $totdbocc Count Change?

The value of $totdbocc is not static. It changes based on certain actions:

• read: Each time a record is read from the database, the counter goes up by 1.
• discard: If you discard a record that was originally from the database, the counter goes down.
• clear: This command completely clears the entity from memory, so the counter resets to 0.

Conclusion

And that's it! $totdbocc is a straightforward function that helps you keep track of the state of your data within a component. By understanding how it relates to $totocc and $hits, you can write more robust and user-friendly Uniface applications.

Happy coding! ✨