The setocc statement is a fundamental command for Uniface 10.4 developers, providing precise control over database record navigation. This guide will demystify setocc, helping you leverage its capabilities to manage data within your applications effectively.

What is setocc?

At its core, setocc (short for “set occurrence”) designates a particular database record as the currently active one. Imagine working with a table of data; setocc allows you to pinpoint and select a specific row, making it the focus of subsequent operations in your Uniface application.

Basic Syntax

The fundamental structure of the setocc command is straightforward:

setocc Entity, OccurrenceNumber

Key Parameters Explained

• Entity: This refers to the name of your database table or data entity (e.g., “PRODUCT,” “EMPLOYEE”).
• OccurrenceNumber: This numerical value specifies which record you wish to activate. A value of 1 selects the first record, 2 selects the second, and so on.

Real-World Examples

Example 1: Accessing the Initial Record

setocc "CUSTOMER", 1

This command makes the very first customer entry the active record, ideal for operations that begin from the start of a dataset.

Example 2: Navigating to the Final Record

setocc "CUSTOMER", -1

Employing -1 as the OccurrenceNumber directs Uniface to the last record in the specified entity, which is highly beneficial for processing the most recent additions.

Example 3: Iterating Through Records

$occ_num$ = 1
repeat
    setocc "ENTRANT", $occ_num$
    ; Perform actions on the current record
    $occ_num$ = $occ_num$ + 1
until ($occ_num$ > $totocc(ENTRANT))

This loop demonstrates how to sequentially visit each record within an entity, akin to reviewing each page of a document.

Special Features and Tricks

Global Entity Control

You can apply setocc across all entities within your component by using "*" in place of a specific entity name:

setocc "*", -1

This powerful feature simultaneously sets all database tables in your component to their respective last records.

Interpreting Return Values

The $status variable provides feedback on the execution of setocc:

• Positive Value: Indicates successful execution, with the value representing the `OccurrenceNumber` of the newly active record.
• Negative Value: Signifies an error. Detailed error information can be found in `$procerror`.

Common Applications

1. Data Integrity Checks: Use `setocc` in conjunction with loops to validate data consistency across all records in a form.
2. Targeted Record Retrieval: Directly jump to specific records without the need for manual browsing through extensive data sets.
3. Automated Processing: Combine `setocc` with iterative structures for efficient batch operations on multiple records.

Essential Considerations

• Uniface occurrence numbers are 1-based (starting from 1), unlike the 0-based indexing common in many programming languages.
• An `OccurrenceNumber` of `0` will preserve the currently active record, making no changes.
• Exercise caution when using `setocc “*”, -1` as it impacts all entities within your component.
• The `getFocus` trigger is activated upon the completion of `setocc`, potentially executing additional code.

Error Management

Expect the following common error codes:

• -1102: Invalid entity name (often due to a typographical error).
• -1203: Attempt to access a record that falls outside the existing range of occurrences.

Best Practices for Robust Code

1. Always Validate `$status`: Implement checks on the `$status` variable after every `setocc` call to manage potential errors gracefully.
2. Descriptive Variables: Opt for clear, descriptive variable names (e.g., `$current_order_line$`) instead of generic ones like `$occ_num$`.
3. Utilize `$totocc`: Integrate `$totocc` to ascertain the total number of records, aiding in loop control and boundary checks.
4. Thorough Testing: Test your `setocc` implementations with diverse data volumes to ensure consistent performance across various scenarios.

Conclusion

The setocc statement is an indispensable element of Uniface development, granting developers granular control over database record selection. Mastery of setocc is crucial for constructing robust, efficient, and user-friendly Uniface applications, whether you’re designing input forms, generating reports, or implementing complex business logic.

Continual practice and experimentation with setocc in your Uniface environment will solidify your understanding and proficiency. Happy coding!