Unlocking Uniface: A Simple Guide to the $ude("import") Function 🚀

(Heads-up! This post was crafted with the help of an AI to break down the official documentation into a more digestible format. 🤖)

If you're working with Uniface, you know that managing your development environment and repository is key. One powerful tool in your arsenal is the $ude("import") function. But what does it do, and how can you use it effectively? Let's break it down in simple terms!

🤔 What is $ude("import") Anyway?

Think of $ude("import") as a special tool for developers. Its main job is to import development objects (like components, entities, and other definitions) from an XML file directly into your Uniface Repository.

⚠️ Crucial Point: This function is for importing development artifacts, not regular application data (like customer lists or product info). For application data, you should use functions like $ude("copy") or entitycopy.

⚙️ How to Use It: The Basic Syntax

The structure of the function looks a bit technical at first, but it's straightforward once you see the parts.

vResult = $ude("import", "misc", Filename, "", OptionsList)

Let's look at the pieces:

• vResult: This is a variable that will hold the result of the import operation (we'll cover that later).
• Filename: The name of the XML file you want to import, like "my_components.xml". You can also import from a zip archive!
• OptionsList: This is where the magic happens! It's a string that lets you control how the import works.

💡 Power-Up Your Import with Options

The OptionsList lets you customize the import. You can combine multiple options using a semicolon (;). Here are a couple of the most useful ones:

supersede=True | False

This is probably the most common option you'll use. It answers one simple question: "If this object already exists in my repository, should I overwrite it?"

• supersede=true: Yes, overwrite the existing object. (This is the default behavior).
• supersede=false: No, do not overwrite it. If it exists, skip it.

commitinterval=Number

When importing a huge number of objects, you might not want to save to the database after every single one. This option tells Uniface how often to commit the changes. For example, commitinterval=100 saves the data after every 100 objects are processed.

✅ Putting It All Together: Examples

Let's look at how this works in the real world with examples from the documentation.

Example 1: Basic Import and Overwrite

This code imports a file named prj_full_acme.xml. Because supersede is not set to false, it will overwrite any existing objects that have the same primary key. It also sets intervals for printing messages and committing to the database.

vResult = $ude("import", "misc", "xml:prj_full_acme.xml", "", "printerinterval=100;commitinterval=100")

Example 2: Import Without Overwriting

Here, we are importing a file whose name is stored in the field cpt_a_service.xml. By setting supersede=false, we ensure that no existing data in our repository will be overwritten.

vResult = $ude("import", "misc", cpt_a_service.xml, "", "supersede=false")

👍 Did It Work? Checking the Results

After running the import, how do you know if it was successful?

• If $ude returns a number >= 0: Success! The number tells you how many records it attempted to process. For more details, you can check the special variable $procReturnContext, which acts like a detailed receipt.
• If $ude returns a number < 0: An error occurred. Check the $procerror variable to see the specific error code.

⚠️ Important Things to Remember

1. Windows Only: The $ude functions can only be used in components or applications that run on Windows.
2. Requires IDE Resources: Your application needs access to the ide.uar file. You can run your component with ide.exe or make sure usys:ide.uar is included in your application's resources.
3. Configured Repository: You must have a fully configured Uniface Repository ready to receive the data.

Wrapping Up

The $ude("import") function is a fantastic utility for Uniface developers to programmatically manage their repository objects. By understanding its simple syntax and powerful options like supersede, you can automate parts of your development and deployment workflows. Happy coding!