The Uniface sort/list statement is a powerful utility for organizing data within Uniface ProcScript. This guide delves into its syntax, diverse sorting options, and practical applications, enabling you to master data arrangement in your Uniface applications.

Uniface’s sort/list Statement: A Comprehensive Guide to Data Sorting

Uniface’s sort/list statement stands out as an exceptionally robust feature within ProcScript, offering flexible and efficient data organization capabilities. Whether you’re managing simple indexed lists, complex associative structures, or nested sublists, this function provides the tools to transform how data is ordered and presented in your applications.

Understanding the Core Syntax

The fundamental structure of the sort/list statement is straightforward:

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

Let’s break down its components:
* List: This refers to the Uniface list you intend to sort. It can be an associative list (ID=Value pairs), an indexed list, or even sublists within a larger structure.
* SortElement: This specifies the particular part of the list item that the sorting operation should focus on, such as $idpart for identifiers or $valuepart for values.
* SortOptions: These are modifiers that dictate the sorting methodology, including order (ascending/descending), uniqueness, data type interpretation, and locale-specific rules.

Decoding Sort Elements

Uniface offers several precise ways to define what your sorting criteria will be:

$idpart – Sorting by Identifier

Primarily for associative lists (where items are stored as ID=Value), $idpart directs the sort to use the identifier string that precedes the equals sign. This is particularly useful when your IDs themselves contain a meaningful sequence, such as numerical codes or structured prefixes.

$valuepart – Sorting by Value

When $valuepart is specified, or when no SortElement is provided (making it the default), the sorting occurs based on the string representation found after the equals sign. This is ideal for alphabetical or numerical sorting of the displayed or stored values themselves.

Sublist Elements – Sorting Nested Data

For more intricate, nested data structures, you can pinpoint specific items within a sublist for sorting. This is achieved by referencing the sublist item’s ID using $string(SublistItemId) or by its sequential position with SublistItemNr.

A Deep Dive into Sort Options

The true power of sort/list comes from its extensive set of SortOptions:

Defining Sort Order 📈📉

• ascending or A: Arranges items in their natural ascending sequence (e.g., A-Z, 1-9). This is the default behavior.
• descending or D: Orders items in the reverse sequence (e.g., Z-A, 9-1).

Ensuring Uniqueness 🎯

• unique or U: This option is invaluable for data cleansing. It processes the list, removes any duplicate entries based on the sort criteria, and retains only unique items in the final sorted list.

Data Type Specific Sorting 🔢

Uniface can interpret list item data as specific types during sorting, ensuring logical order:
* Numeric: Sorts data as numerical values (e.g., ‘2’ comes before ’10’).
* Float: Handles decimal numbers accurately.
* Date: Arranges items chronologically based on their date value.
* Boolean: Sorts items based on their true/false logical state.
* level: A specialized sorting option for hierarchical identifiers (e.g., ‘9.2’ correctly precedes ‘10.1’).

Locale-Aware Sorting 🌍

For international applications, sort/list supports locale-specific sorting:
* nlslocale or NLS: Applies sorting rules defined by the current National Language Support (NLS) locale settings.
* CaseSensitive or CS: Performs string comparisons where ‘A’ is distinct from ‘a’.
* CaseInsensitive or CI: Ignores case during string comparisons, treating ‘A’ and ‘a’ as identical.

Practical Scenarios and Examples

Let’s illustrate the sort/list statement with some real-world examples:

Example 1: Simple Color List Manipulation

Consider a list of colors:

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 is now "2=GREEN;1=RED;0=BLUE"

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

Example 2: Alphabetizing a Dropdown Field

A common use case is sorting ValRep (Value Representation) lists for dropdown fields:

trigger getFocus; on Entity
    vStates = $valrep(STATE) ; Get the current ValRep for the STATE field
    sort/list vStates, "A"   ; Sort the states alphabetically
    ; vStates is now "al=Alabama;ak=Alaska;az=Arizona;ar=Arkansas"...
    $valrep(STATE) = vStates ; Assign the sorted list back to the field
end ; getFocus

This snippet ensures that your dropdown lists are always presented in an organized, user-friendly alphabetical order.

Example 3: Multi-Criteria Sorting

For complex data, you can specify multiple sort criteria, which Uniface processes sequentially:

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

Return Values and Error Handling

The sort/list statement communicates its outcome via the $status variable:
* < 0: Indicates an error occurred. Consult $procerror for detailed error information.
* 0: Denotes successful execution.
* >= 0: Reports the number of items remaining in the list after sorting (useful, for instance, with the unique option).

Common Errors to Anticipate ⚠️

• -1112 (UPROCERR_OPTION): An invalid or unrecognized sort option was supplied.
• -1101 (UPROCERR_FIELD): The specified field does not exist, often encountered when sorting entity-related lists.
• -1129 (UPROCERR_ITEM): A referenced sublist item ID or number could not be found.

Best Practices and Optimization Tips

To maximize the effectiveness and efficiency of sort/list:

• Performance Considerations: Bear in mind that sorting operations are typically based on the first 8KB of an item’s data. For very large datasets, consider filtering the data before sorting to reduce the processing load.
• Locale Awareness: For applications targeting diverse linguistic regions, accurately set the $nlssortorder and $nlslocale variables. This ensures character ordering aligns with regional conventions.
• Type Safety: When employing data type-specific sorting options (e.g., Numeric, Date), verify that your list data is consistently interpretable as the specified type. Mixed data types can lead to unpredictable results.
• Multi-Level Sorting Strategy: Leverage the power of multiple sort criteria separated by semicolons. Uniface processes these criteria in the order they are listed, enabling sophisticated, granular sorting.

Advanced Applications

Dynamic Sort Configuration

You can construct sort options dynamically based on user preferences or application logic:

vSortOptions = ""
if (vUserPref = "NAME")
    vSortOptions = "$valuepart:ascending"
else
    vSortOptions = "$idpart:descending numeric"
endif
sort/list (vDataList, vSortOptions)

Unique Value Extraction

The unique option is perfect for creating lists of distinct values:

; Sort and remove duplicate entries
sort/list (vCategoryList, "$valuepart:ascending unique")
; vCategoryList now contains only unique categories, sorted alphabetically

Seamless Integration with Uniface Features

The sort/list function integrates effortlessly with other Uniface list operations:
* List Management: Use it alongside putitem to add items and getitem to retrieve them, facilitating complete list control.
* Iterative Processing: Combine with forlist loops to process data that has already been sorted, ensuring orderly iteration.
* UI Integration: Its synergy with $valrep assignments is crucial for dynamically sorting dropdown and selection fields.
* Complex Data Manipulation: Chain sort/list with other list functions like delitem for sophisticated data restructuring.

Conclusion: Empowering Your Uniface Applications

The sort/list statement is an indispensable and highly adaptable tool that significantly enhances data organization within Uniface applications. From straightforward alphabetical arrangements to intricate multi-tiered sorting, a thorough understanding of its capabilities will not only make your ProcScript more robust but also elevate the user-friendliness of your applications.

Whether you’re streamlining dropdowns, processing database query results, or managing complex in-memory data structures, sort/list provides the unparalleled flexibility and control you require. Always remember to validate the return status and implement proper error handling to ensure the resilience and reliability of your applications.

Happy coding with Uniface! Share your experiences or questions about list sorting in the comments below.