Demystifying Uniface: A Simple Guide to the $totkeys Function ✨

#tutorial #programming #database

Quick note: This blog post was outlined and drafted with the help of an AI to ensure clarity and accuracy based on the official documentation.

Hello, fellow developers! 👋 If you're working with the Rocket Uniface platform, you know it has a rich scripting language called ProcScript. Today, we're going to dive into a small but very handy function: $totkeys.

What Exactly is $totkeys? 🤔

In simple terms, $totkeys is a built-in ProcScript function that tells you the total number of keys defined for a specific entity (which is Uniface's term for a database table). This isn't just about primary keys; it counts everything:

Primary Keys
Candidate Keys
Indexes

Knowing this number is incredibly useful when you need to programmatically inspect or validate the structure of your entities without hardcoding values.

How Do You Use It? 💻

The syntax is very straightforward:

$totkeys { ( Entity ) }

The Entity parameter is a string containing the name of the entity you want to inspect. The best part? It's optional! If you omit it, Uniface automatically uses the current entity in your component's context. This makes your code cleaner and more dynamic.

The function will return a number (like 3, 5, etc.) representing the total count of keys. If something goes wrong, it will return an empty string.

Let's See a Real-World Example 🚀

Imagine you have a batch process and you want to ensure all primary ("P") and candidate ("C") keys for an entity are validated before proceeding. Instead of manually checking each key, you can use $totkeys to loop through them all.

Here’s how you could do it:

; Initialize a counter
$KEYNBR$ = 1
; Get the total number of keys for the current entity
$MAXKEYS$ = $totkeys

; Loop from the first key to the last
while ($KEYNBR$ <= $MAXKEYS$)
  ; Check if the key type is Primary ('P') or Candidate ('C')
  if ($keytype($entname, $KEYNBR$) = "P" | $keytype($entname, $KEYNBR$) = "C")
    ; If it is, run the standard validation for that key
    validatekey $entname, $KEYNBR$
  endif
  ; Move to the next key
  $KEYNBR$ = $KEYNBR$ + 1
endwhile

This code is robust because it will automatically adapt if a developer adds or removes a key from the entity later on. No magic numbers needed!

What Happens When Things Go Wrong? 😬

Good code anticipates errors. If you pass an entity name that doesn't exist or isn't available in the current component, $totkeys will return an empty string. To find out what exactly went wrong, you can check the global $procerror variable. A common error code is -1102, which means the entity name was invalid.

Wrapping Up! 🎁

And that's it! The $totkeys function is a perfect example of a simple tool in ProcScript that helps you write more dynamic and maintainable code. It gives you a clean way to access an entity's metadata without any fuss.

Happy coding! 🎉