🚀 Understanding Uniface 10.4 Exception Handling with the throw Statement

📝 This blog post was created with AI assistance to help developers understand Uniface exception handling.

🎯 What is the throw Statement?

The throw statement in Uniface 10.4 is your tool for creating custom exceptions. Think of it as a way to "raise a red flag" 🚩 when something goes wrong in your application that you want to handle in a specific way.

📋 Basic Syntax

throw ErrorNumber {, Description {, AdditionalInformation} }

🔧 Parameters Explained

ErrorNumber (Required) 📊

This is a numeric value that identifies your error. Here's what you need to know:

• Always use negative numbers (Uniface converts positive numbers to negative automatically)
• Avoid numbers between -1 and -9999 (these are reserved for Uniface system errors)
• If you use 0, Uniface throws it as -1

Description (Optional) 📝

A brief, easy-to-understand text that explains what went wrong. If you don't provide this, Uniface uses "Custom exception" as default.

AdditionalInformation (Optional) ℹ️

Extra details about the error - think of it as the "fine print" that helps with debugging.

💡 Practical Example

Let's look at a real-world example from an order processing system:

public operation loadOrder
throws
params
 string pOrderId : IN
endparams
 if (pOrderId == "")
 throw -10001, "Invalid input parameter", "PARAM_INDEX=1;PARAM_NAME=pOrderId;EXPECTED_VALUE=Not NULL"
 endif
 ID.ORDER/init = pOrderId
 retrieve/e "ORDER"
end

In this example:

• -10001 is our custom error number
• "Invalid input parameter" tells us what's wrong
• The additional information gives specific details about which parameter failed

🔄 How Exception Bubbling Works

Exception bubbling means that when an error occurs, it "travels up" through your code until it finds something that can handle it. Here's how it works:

Inside a try-catch Block 🛡️

If your throw statement is inside a try...catch...endtry block, the program looks for a matching catch block:

try
 retrieve
 throw -10054, "Description", "more context list"
catch -2, -4, -10054
 ; code to handle the expected exceptions
endtry

Outside try-catch Blocks ⬆️

If there's no try-catch block, the exception "bubbles up" to the calling code. This is useful for operations that declare throws.

🎛️ System Variables After throw

When you use throw, Uniface automatically sets these system variables:

• $procerror - Contains your ErrorNumber
• $procerrorcontext - Contains DESCRIPTION and ADDITIONAL items

✅ Best Practices

1. Use meaningful error numbers - Pick numbers that make sense for your application (e.g., -20001 for database errors, -30001 for validation errors)
2. Write clear descriptions - Make them human-readable, not cryptic codes
3. Include useful additional information - Help future developers (including yourself) debug issues
4. Document your error codes - Keep a list of what each error number means

🚀 Why Use Custom Exceptions?

Custom exceptions help you:

• Handle specific business logic errors differently from system errors
• Provide better error messages to users
• Make your code more maintainable and debuggable
• Create consistent error handling across your application

The throw statement is a powerful tool for creating robust, maintainable Uniface applications. By using it wisely, you can build applications that handle errors gracefully and provide meaningful feedback to both users and developers! 🎉