🔧 Mastering Uniface $collhandle: Working with Entity Collections in Uniface 10.4

⚠️ This blog post was created with the assistance of AI to provide accurate and comprehensive information about Uniface development.

When working with Uniface 10.4, managing multiple entity occurrences efficiently is crucial for building robust applications. The $collhandle function is your gateway to working with entity collections and performing operations on multiple records at once! 📊

🤔 What is $collhandle?

The $collhandle function returns a handle (think of it as a reference or pointer) to a specified entity collection. This handle allows you to work with all occurrences of an entity, or just the selected ones, through collection operations.

Handle: A reference to an object (like an entity, occurrence, or component) that lets you call operations and access attributes on that object.

Entity: In Uniface, this represents a logical data structure, similar to a database table.

Occurrence: This is like a single row or record in your entity - one instance of your data.

📝 Basic Syntax

$collhandle { ( Entity ) }{-> $selectedoccs | $clearselection()}

The curly braces { } indicate optional parameters. You can use it in several ways:

$collhandle - Works with the current entity
$collhandle("CUSTOMER") - Works with the CUSTOMER entity specifically
$collhandle("CUSTOMER")->$selectedoccs - Gets selected CUSTOMER occurrences
$collhandle("CUSTOMER")->$clearselection() - Clears selection on CUSTOMER occurrences

💡 Practical Example

Here's a real-world example showing how to work with selected customer records:

; Get a handle to selected CUSTOMER occurrences
vStruct1 = $collhandle("CUSTOMER")->$selectedoccs

; Process each selected customer
variables
    handle vCustomerHandle
    numeric vCounter
endvariables

vCounter = 1
while (vStruct1{vCounter} != "")
    ; Get handle to individual customer
    vCustomerHandle = vStruct1{vCounter}

    ; Now you can call operations on this customer
    vCustomerHandle->updateDiscountStatus()

    vCounter = vCounter + 1
endwhile

; Clear the selection when done
$collhandle("CUSTOMER")->$clearselection()

🎯 Working with Selected Occurrences

The $selectedoccs attribute is particularly powerful. It returns a Struct (Uniface's data structure similar to an array) containing handles to all selected occurrences.

Struct: A data structure in Uniface that can hold multiple values, similar to an array in other programming languages.

You can access individual struct members using the index operator: vStruct{N} where N is the position number.

⚠️ Important Requirements

To use $collhandle effectively, you need at least one public operation defined in the entity's Collection Operations container. Without public operations, the function returns NULL because no signature can be created for the entity.

Collection Operations: Special operations in Uniface that work on multiple occurrences of an entity at once, rather than individual records.

🔧 Return Values and Error Handling

The function returns different values depending on the situation:

> 0: Valid handle to the entity collection ✅
NULL: Something went wrong ❌
- Invalid entity name
- No occurrences found
- No public operations defined
- Other error (check $procerror)

Always check for errors using $procerror:

vHandle = $collhandle("CUSTOMER")
if (vHandle = "")
    if ($procerror = -1102)
        ; Entity name invalid or not painted on component
        $1 = "Error: Invalid entity name"
    endif
endif

🚀 Advanced Usage Tips

Selection Management: Use $occhandle->$selected to check or set whether individual occurrences are selected.

Batch Processing: Perfect for operations that need to process multiple records efficiently, like bulk updates or calculations.

Component Integration: The entity must be painted (visually present) on the current component to use $collhandle.

🎉 Conclusion

The $collhandle function is essential for working with multiple entity occurrences in Uniface applications. It provides a clean, efficient way to perform batch operations while maintaining full control over which records are processed. Remember to always define public collection operations and handle potential errors gracefully! 🎯

Keywords: