DEV Community

Peter + AI
Peter + AI

Posted on

🚀 Mastering Asynchronous Communication in Uniface with postmessage

#uniface #messaging #asynchronous #procscript

As a developer working with Uniface applications, understanding inter-component communication is crucial for building robust and scalable systems. Today, let's dive deep into one of Uniface's most powerful features: the postmessage statement! 📨

This article is based on the Uniface Documentation 10.4, and I had assistance from AI to structure and present this information clearly.

🎯 What is postmessage?

The postmessage statement is Uniface's way of sending messages from one component instance to another. Think of it as a postal service for your application components - it delivers messages asynchronously, allowing different parts of your application to communicate without blocking each other's execution.

📝 Basic Syntax 

postmessage Destination, MessageId, MessageData
Enter fullscreen mode Exit fullscreen mode

Where the Destination follows this pattern:

{InstancePath :}InstanceName
Enter fullscreen mode Exit fullscreen mode

🔧 Key Parameters Explained

Parameter Type Description
Destination String The target component instance 🎯
MessageId String Message identifier (1-32 characters) 🏷️
MessageData String The actual message payload 📦

🌐 Network Communication

For remote communication, you can specify an InstancePath with this structure:

NetworkMnemonic : { HostId }{+ PortNumber} | UserName | | SymbolicName
Enter fullscreen mode Exit fullscreen mode

Common examples:

  • TCP:myserver:13001 - Connect to myserver on port 13001
  • TCP:192.168.1.100 - Connect to specific IP (default port 13001)
  • TCP:localhost - Local machine communication

📊 Return Values & Error Handling

✅ Success Values ($status)

  • 0: Message successfully queued (not necessarily delivered!)
  • -2: Invalid instance name
  • -3: Invalid message identifier

🚨 Common Errors ($procerror)

  • -57: Instance not found in component pool
  • -159: Message delivery failed
  • -1105: Invalid instance name format
  • -1107: Invalid or non-existent path

🔄 Message Flow & Processing

Here's how message processing works:

  1. Sending: postmessage places the message in a queue
  2. Routing: Uniface Router dispatches the message (if remote)
  3. Reception: Target component's receiveMessage trigger fires
  4. Processing: Message data becomes available via $msginfo

💡 Practical Example: Master-Detail Communication

Let's look at a real-world scenario: a recipe management system where a list component needs to stay synchronized with detail editing components.

🍳 The Detail Component (RCP_UPDATE) 

; RCP_UPDATE component - store trigger
trigger store 
    store
    if ($status < 0)
        message $text(1500)
        rollback
        commit
    else
        if ($status = 1)
            message $text(1723)
        else
            commit
            if ($status < 0)
                rollback
                commit
            else
                message $text(1805)
                ; 📨 Notify the list component!
                postmessage "RCP_LIST", $componentname, RCP_NR.RECIPES
                setformfocus "RCP_LIST"
            endif
        endif
    endif
end; store trigger
Enter fullscreen mode Exit fullscreen mode

📋 The List Component (RCP_LIST) 

; RCP_LIST component - receiveMessage trigger
trigger receiveMessage
    RCP_NR = $msgdata                    ; Get the record number

    if ( $msgid = "RCP_UPDATE" )         ; Handle updates
        reload/nolock "RECIPES"
    endif

    if ( $msgid = "RCP_NEW" )            ; Handle new records
        retrieve/x "RECIPES"
    endif

    if ( $msgid = "RCP_UPDATE" | $msgid = "RCP_NEW")
        sort "RECIPES", "RCP_NAME:A"     ; Re-sort the list
        retrieve/o "RECIPES"             ; Make updated record current
    endif
end ; receiveMessage
Enter fullscreen mode Exit fullscreen mode

🔍 Message Information Functions

When processing received messages, these functions provide valuable context:

  • $msgid - The message identifier
  • $msgdata - The message payload
  • $msgsrc - Source component information
  • $msgdst - Destination details
  • $instancename - Current instance name
  • $instancepath - Network path information

⚡ Performance Tips & Best Practices

🚀 Do's

  • Use for asynchronous communication - Perfect for notifications and updates
  • Keep message data lightweight - Only send essential information
  • Handle errors gracefully - Always check $status and $procerror
  • Implement acknowledgments - When delivery confirmation is needed

⚠️ Don'ts

  • Don't use for synchronous operations - Use activate instead
  • Don't assume delivery - Status 0 only means "queued"
  • Don't send massive payloads - Memory is the only limit, but be reasonable

🎯 Key Takeaways

The postmessage statement is a powerful tool for building responsive, loosely-coupled Uniface applications. By mastering asynchronous messaging, you can:

  • ✨ Create more responsive user interfaces
  • 🔧 Build modular, maintainable component architectures
  • 🌐 Enable distributed application scenarios
  • 📈 Improve overall application scalability

Whether you're building simple master-detail forms or complex distributed systems, postmessage provides the foundation for robust inter-component communication in your Uniface applications! 🚀

Have you used postmessage in your Uniface projects? Share your experiences and tips in the comments below! 💬

Top comments (0)