Mastering Data Copying in Uniface 10.4 with $ude("copy") 🚀

Hello developers! 👋 If you're working with Uniface, you know that moving data around is a common task. Whether you're migrating data to a new system, creating test datasets, or just exporting information, you need a reliable tool. In Uniface, one of the most powerful functions for this is $ude("copy").

Let's dive into how you can use this function to make your life easier. It's a bit old-school, but incredibly useful once you get the hang of it.

(Disclaimer: This blog post was created with the help of an AI assistant to structure the information from the official documentation and make it more accessible. All technical details were reviewed.)

What Exactly is $ude("copy")? 🤔

At its core, $ude("copy") is a ProcScript function that copies entity occurrences (think of these as records or rows in a table) from a source to a destination. This source or destination can be a database or an XML file.

The basic syntax looks like this:

vResult = $ude("copy", "misc", Source, Target, {OptionList})

• Source: Where the data is coming from. This could be a database entity (like "def:MYENTITY.MYMODEL") or an XML file ("mydata.xml").
• Target: Where the data is going. This could be a database path (like "def:") or a new XML file ("mynewdata.xml").
• OptionList: This is where the magic happens! It's a list of options that give you fine-grained control over the copy process.

Basic Copy Operations 📦➡️💾

Let's start with some simple examples to see it in action.

Example 1: Copying a Database Entity to an XML File

Imagine you have an entity called "ORDERS" in your model "SALES" and you want to export all its data to an XML file.

variables
  numeric vResult
endvariables

vResult = $ude("copy", "misc", "def:ORDERS.SALES", "orders_export.xml")

if (vResult < 0)
  message "An error occurred during the copy process: " %%$procerror
else
  message "Successfully processed %%vResult records."
endif

This command reads all occurrences from the ORDERS entity and writes them into a new file named orders_export.xml.

Example 2: Copying an XML File into the Database

Now, let's do the reverse. You have an XML file with data and want to load it into your default database path.

variables
  numeric vResult
endvariables

vResult = $ude("copy", "misc", "orders_import.xml", "def:")

if (vResult < 0)
  message "An error occurred during the import: " %%$procerror
else
  message "Successfully processed %%vResult records."
endif

Uniface will read orders_import.xml and attempt to write the records into the corresponding entities in the database defined by the def: path.

Unlocking Advanced Features with OptionList ⚙️

The real power of $ude("copy") comes from its optional parameters. Here are a few of the most useful ones.

Filtering Data with where\

You probably don't want to copy all your data every time. The where option lets you specify conditions to select only the records you need.

; Copy only orders with an amount greater than 1000
vResult = $ude("copy", "misc", "def:ORDERS.SALES", "large_orders.xml", "where=AMOUNT > 1000")

Controlling Overwrites with supersede\

What happens if a record you're copying already exists in the target database? By default, $ude("copy") will overwrite it. You can prevent this by setting supersede=False.

; Copy data, but do not overwrite existing records with the same primary key
vResult = $ude("copy", "misc", "new_data.xml", "def:", "supersede=False")

Transforming Data with map\

Sometimes the source and target data structures don't match. The map option allows you to define rules for how to map source fields to different target fields. This is a more advanced topic, but it's essential for complex data migrations.

; Use the target repository's definitions to map all entities
vResult = $ude("copy", "misc", "def:OLD_ORDERS.V1", "def:", "map=#")

Common Pitfalls & Best Practices ⚠️

While $ude("copy") is powerful, there are a few traps to be aware of.

🚨 DO NOT Use for Repository Definitions!

This is the most important warning. Never use $ude("copy") to move repository objects like forms, services, or entities between different repositories. Doing so can corrupt your repository. Always use $ude("export") and $ude("import") for this purpose.

The Mysterious "Error 8066"

If you see an error like 8066 - Copy failed: Open error on input file/table, it almost always means that Uniface cannot find the entity descriptor (.edc file). Make sure you have compiled the entity you are trying to copy from. The compiler generates this essential file.

You're in Charge of Data Integrity

$ude("copy") performs a physical data copy. It does not check for referential integrity. For example, if you copy an OrderItem\ but not its parent Order\, the function will not stop you. It's your responsibility as the developer to ensure you copy all related data to keep your database consistent.

Understanding the Return Value

The return value of $ude("copy") is the number of records it *attempted* to process, not the number of successful writes. For detailed results, including the number of records written, skipped, or failed, you should inspect the $procReturnContext function after the operation.

Conclusion

The $ude("copy") function is a workhorse for data handling in Uniface. While it has its quirks, understanding its basic usage, powerful options, and common pitfalls will enable you to perform data migration and manipulation tasks with confidence. Happy coding! ✨