🚀 Creating an Application Server Shell in Uniface 10.4: A Step-by-Step Guide

✨ This blog post was created with AI assistance to help developers understand Uniface better.

📋 What is an Application Server Shell?

An Application Server Shell is a special software module in Uniface that defines how your server application starts and behaves 🖥️. Think of it as the "control center" that initializes and manages your server environment before any components start running.

When you need customized behavior for your Uniface server - like user authentication, logging, or specific initialization tasks - you create an Application Server Shell to handle these requirements.

🎯 Why Do You Need It?

Application Server Shells are essential when you want to:

• Authenticate users before they access specific components or operations 🔐
• Initialize the application environment with custom settings ⚙️
• Define global behavior that applies to all server requests 🌐
• Handle messages and requests in a standardized way 📨

🛠️ How to Create an Application Server Shell

Prerequisites

Before you start, make sure you have created a project to contain your application definitions. Projects help you organize and manage all your Uniface objects in one place 📁.

Step-by-Step Instructions

Step 1: Open Your Project 📂

In the U-Bar (Uniface's main navigation), click Browse, select prj (project), and choose the project you want to work with.

Step 2: Create the Shell ➕

Go to the Templates tab in the Resource Browser. Find the Windows Shell template, then drag and drop it onto your project object in the Structure view. This creates a new application shell in your project.

Step 3: Open the Shell Editor ✏️

Right-click your new application shell and select Open. This opens it in the Application Shell Editor where you can configure all its properties.

Step 4: Set the Shell Type 🔧

Check the Shell Type property in the Properties Inspector. It should be set to APU (which stands for Application Server). This tells Uniface that this shell is meant for server applications, not desktop applications.

Step 5: Configure Properties ⚙️

In the Properties Inspector, set up your shell's configuration properties:

• If you have defined global objects like messages or global ProcScripts, select the Library that contains these objects
• To define custom properties, click the More icon (⋮) in the More Properties section. This opens the Define Application Shell Properties dialog where you can add your own properties

Step 6: Write ProcScript Code 💻

In the script editor, write ProcScript to define how your application initializes and responds to events. This is where the real magic happens! ✨

Important Triggers for Server Shells

Server shells have three special triggers (event handlers) that you can use:

1. receiveMessage Trigger 📥

This trigger handles incoming messages to your server. Use it to process requests and route them to the appropriate components.

2. preRequest Trigger 🔒

This trigger runs before a component operation is activated. This is perfect for authentication! For example, you can check if a user is logged in before allowing them to access a specific component.

3. postRequest Trigger ✅

This trigger runs after a component operation completes. Use it for logging, cleanup tasks, or sending response data.

Example: User Authentication

Here's a practical example of how you might use the preRequest trigger for user authentication in a web application server:

trigger preRequest
    ; Check if user is authenticated
    if ($user_id = "")
        ; User is not logged in
        putmess "Authentication required"
        return -1  ; Reject the request
    endif

    ; User is authenticated, allow request to proceed
    return 0
end ; preRequest

In this example, the server checks if a user is logged in (by checking if $user_id has a value). If not, it displays an error message and rejects the request by returning -1. If the user is authenticated, it returns 0 to allow the request to continue 🎉.

🎬 Compile and Deploy

Step 7: Compile Your Shell 🔨

Once you've written your ProcScript code, click Compile to compile the application shell. This converts your code into executable form that Uniface can run.

After successful compilation, your Application Server Shell is ready to use! Your server will now follow the custom behavior you defined whenever it starts or processes requests.

🔑 Key Terms Explained

ProcScript: Uniface's programming language for defining application behavior and business logic 📝

Trigger: A block of code that runs automatically when a specific event occurs (like receiving a request or starting the application) ⚡

Component: A reusable unit of functionality in Uniface, such as a form, service, or report 🧩

APU (Application Server): The server type designation for shells that run server-side operations 🖥️

💡 Common Use Cases

Application Server Shells are commonly used for:

• Security: Authenticating and authorizing users before processing requests 🛡️
• Logging: Recording all server activities for audit trails 📊
• Environment Setup: Initializing database connections, loading configuration files, or setting up resources 🔧
• Error Handling: Catching and managing errors in a centralized way ⚠️
• Session Management: Managing user sessions and state information 🔄

⚠️ Common Issues and Solutions

Issue: Shell doesn't execute my code

Solution: Make sure you compiled the shell after making changes. Uniface only runs compiled code, not the source code.

Issue: Properties not accessible

Solution: Verify that you've correctly defined custom properties in the Define Application Shell Properties dialog and that they're spelled correctly in your code.

Issue: Triggers not firing

Solution: Check that the Shell Type is set to APU (Server). Desktop shells use different triggers than server shells.

🎉 Conclusion

Creating an Application Server Shell in Uniface 10.4 gives you powerful control over your server's behavior. Whether you're building a web application, implementing security measures, or customizing how your server processes requests, the Application Server Shell is your starting point 🚀.

By following these steps and using the three main triggers (receiveMessage, preRequest, and postRequest), you can create robust, secure, and well-organized server applications.

Have you created an Application Server Shell in Uniface? What challenges did you face? Share your experiences in the comments below! 💬