🚀 Mastering Uniface `sort/list`: Complete Guide to List Sorting in ProcScript

This blog post was created with AI assistance 🤖 based on Uniface 10.4 documentation

The sort/list statement is one of the most powerful tools in Uniface ProcScript for organizing data efficiently. Whether you're working with associative lists, indexed lists, or complex sublists, this function provides flexible sorting capabilities that can transform how you handle data in your applications! 🎯

📝 Basic Syntax and Structure

The sort/list statement follows this pattern:

sort/list List, "SortElement {:SortOptions} {;SortElement{:SortOptions}}"

Here's what each part means:

• List: The Uniface list you want to sort (can be associative, indexed, or sublists)
• SortElement: What part of the list to sort on (like $idpart or $valuepart)
• SortOptions: How to sort (ascending, descending, unique, data type, etc.)

🎛️ Understanding Sort Elements

Uniface provides several ways to specify what to sort on:

$idpart - Sort by ID Part

For associative lists (ID=Value pairs), $idpart sorts based on the identifier before the equals sign. This is particularly useful when your IDs have meaningful ordering like numbers or codes.

$valuepart - Sort by Value Part

This sorts based on the representation after the equals sign. It's the default behavior when no sort element is specified, making it perfect for alphabetical sorting of display values.

Sublist Elements

For complex nested structures, you can sort by specific sublist items using $string(SublistItemId) or by sequence number with SublistItemNr.

⚙️ Sort Options Explained

The power of sort/list lies in its extensive sorting options:

Sort Order 📈📉

• ascending or A: Default ascending order (A to Z, 1 to 9)
• descending or D: Reverse order (Z to A, 9 to 1)

Uniqueness 🎯

unique or U: Removes duplicate entries, keeping only unique items in your sorted list.

Data Type Sorting 🔢

Uniface can sort data as specific types:

• Numeric: Treats data as numbers (10 comes after 2, not before)
• Float: For decimal numbers
• Date: Chronological date sorting
• Boolean: True/false values
• level: Special sorting for hierarchical IDs (9.2 before 10.1)

Locale-Based Sorting 🌍

• nlslocale or NLS: Uses locale-specific sorting rules
• CaseSensitive or CS: Case-sensitive string comparison
• CaseInsensitive or CI: Case-insensitive comparison

💡 Practical Examples

Example 1: Basic Color List Sorting

vColors = ""
putitem/id vColors "0", "BLUE"
putitem/id vColors "1", "RED"  
putitem/id vColors "2", "GREEN"

; Sort by ID part in descending numeric order
sort/list (vColors, "$idpart: descending numeric")
; Result: vColors = "2=GREEN;1=RED;0=BLUE"

; Sort by value part (default)
sort/list (vColors, "ascending")
; Result: vColors = "0=BLUE;2=GREEN;1=RED"

Example 2: State Dropdown Field Sorting

trigger getFocus; on Entity
    vStates = $valrep(STATE)
    sort/list vStates,"A" 
    ; vStates is now "al=Alabama;ak=Alaska;az=Arizona;ar=Arkansas"...
    $valrep(STATE) = vStates
end ; getFocus

This example shows a common pattern: copying a field's ValRep (Value Representation list) to a variable, sorting it, then assigning it back to make dropdown lists alphabetically organized.

Example 3: Multi-Level Sorting

; Sort first by category, then by name within each category
sort/list (vProducts, "$idpart:ascending;$valuepart:ascending")

🔄 Return Values and Error Handling

The sort/list statement provides feedback through the $status variable:

• < 0: An error occurred (check $procerror for details)
• 0: Success
• >= 0: Number of items remaining in the list

Common Errors to Watch For ⚠️

• -1112 (UPROCERR_OPTION): Invalid sort option specified
• -1101 (UPROCERR_FIELD): Field doesn't exist when sorting entities
• -1129 (UPROCERR_ITEM): SubItem ID or number doesn't exist

🏆 Best Practices and Tips

Performance Considerations

Remember that sorting is based on the first 8K of item data. For large data sets, consider whether you need to sort the entire list or can filter first.

Locale Awareness

The values of $nlssortorder and $nlslocale determine locale-based sorting rules. Set these appropriately for international applications to ensure proper character ordering.

Type Safety

When using data type sorting options, ensure your data can be interpreted as the specified type. Mixed data types in a list can lead to unexpected results.

Multi-Level Sorting Strategy

For complex sorting requirements, you can specify multiple sort criteria separated by semicolons. Uniface processes these in order, providing sophisticated sorting capabilities.

🎯 Advanced Use Cases

Dynamic Sort Configuration

; Build sort options dynamically based on user preferences
vSortOptions = ""
if (vUserPref = "NAME")
    vSortOptions = "$valuepart:ascending"
else
    vSortOptions = "$idpart:descending numeric"
endif
sort/list (vDataList, vSortOptions)

Unique Value Extraction

; Remove duplicates while sorting
sort/list (vCategoryList, "$valuepart:ascending unique")
; Now vCategoryList contains only unique categories in alphabetical order

🚀 Integration with Other Uniface Features

The sort/list function works seamlessly with other Uniface list operations:

• Use with putitem and getitem for complete list management
• Combine with forlist loops for processing sorted data
• Integrate with $valrep assignments for dropdown field sorting
• Chain with other list functions like delitem for complex data manipulation

🎉 Conclusion

The sort/list statement is an incredibly versatile tool that can dramatically improve data organization in Uniface applications. From simple alphabetical sorting to complex multi-level data arrangement, understanding its options and capabilities will make your ProcScript more powerful and your applications more user-friendly!

Whether you're organizing dropdown lists, processing database results, or managing complex data structures, sort/list provides the flexibility and control you need. Remember to always check the return status and handle errors appropriately for robust application behavior.

Happy coding with Uniface! 🎊 Do you have questions about list sorting or other Uniface development topics? Feel free to share your experiences in the comments!