For developers working with Uniface 10.4 who need to execute operating system commands directly from their applications, the spawn statement is an essential tool. This guide will explore its functionality, syntax, and best practices.

Understanding the spawn Command

The spawn statement is a fundamental ProcScript command that enables a Uniface application to pass and execute commands on the underlying operating system. It acts as a direct interface between the Uniface environment and system-level operations. ProcScript is Uniface’s proprietary scripting language, used to implement application logic and behavior.

Basic Syntax

The syntax for spawn is straightforward:

spawn OSCommand

OSCommand is a string literal or variable containing the operating system command to be executed. This string can be up to 2047 bytes in length.

How spawn Operates

Upon execution of a spawn statement, the following occurs:

• The current screen display is typically cleared.
• The specified command is dispatched to the operating system.
• By default, the command runs as an asynchronous process. This means the Uniface application continues its execution without waiting for the operating system command to complete.
• In some interactive or character-mode applications, a refresh command may be necessary afterward to restore or update the screen display.

An asynchronous process operates independently in the background, allowing the primary application thread to proceed without interruption.

Return Values and Status

The spawn command populates the system variable $status to indicate the outcome of the execution:

• 0: Indicates successful execution of the operating system command.
• Less than 0: Signifies that an operating system error occurred during the command’s execution.

If the command executes successfully ($status is 0), the $result system variable will contain any value returned by the operating system command itself.

Platform-Specific Behaviors

The spawn command exhibits slightly different behaviors depending on the operating system:

Windows Environments

On Windows, spawn commands can be made to run synchronously by prefixing the command string with a hash symbol (#). A synchronous process will block the Uniface application until the operating system command has finished executing.

Example (Windows Synchronous):

; This waits for the program to finish
spawn "#conv_val.exe %%vFile.raw"
; Now we can safely load the processed file
fileload "%%$1.dat",vValues

In this example, fileload will only execute after conv_val.exe has completed.

Unix/Linux Environments

Unix-based systems offer explicit control over synchronous and asynchronous execution:

• Synchronous: spawn OSCommand (the application waits for completion).
• Asynchronous: spawn OSCommand& (the application continues immediately, signified by the ampersand &).

Practical Implementations

Example 1: File Maintenance (Unix)

This Unix example demonstrates interactively removing specific print files:

trigger detail
    spawn "rm -i *.p[0-9][0-9] "
    askmess "Press space bar to return."," ",-1
    refresh
end

The -i flag ensures the user is prompted for confirmation before deleting each matching file.

Example 2: Opening Files (Windows)

This Windows example uses CMD.exe to open a specified file with its default associated application:

$st_execute$ = "CMD.exe /c %%$file_name$%%"
spawn "#%%$st_execute$"

By using the # prefix, the Uniface application waits until the launched application (e.g., a PDF reader, image viewer) is closed, or the command itself finishes.

spawn vs. activate with OS Services

Choosing between spawn and activate with OS services depends on the interaction requirements:

• Use spawn: For launching interactive applications where output capture isn’t critical, or for simple fire-and-forget commands.
• Use activate with OS services: When there’s a need to capture the output of a command, or for more controlled execution of non-interactive background processes, particularly in server-side contexts. OS Services are Uniface components designed for robust operating system interaction.

Important Considerations

Component Compatibility

The spawn statement is universally available across all Uniface component types, including forms, services, and reports.

Client/Server Architecture

In client/server deployments, the spawn command executes on the client machine where the Uniface application interface is running, not on the server. This distinction is crucial for command pathing and resource access.

Screen Refresh Requirement

Especially in character-mode Uniface applications, a refresh command may be necessary after spawn to ensure the display is updated correctly, as spawn can clear the screen.

Best Practices for spawn

1. Error Handling: Always check the $status variable immediately after a spawn command to gracefully handle any operating system errors.
2. Absolute Paths: Rely on absolute file paths for commands and executables to avoid issues with environment variables or current working directories.
3. Security Validation: If any part of the OSCommand originates from user input, rigorously validate and sanitize it to prevent command injection vulnerabilities.
4. Cross-Platform Testing: Acknowledge and test for the nuanced differences in spawn behavior between Windows and Unix/Linux environments.

When to Avoid spawn

Consider alternatives to spawn in the following scenarios:

• When you need to reliably capture the standard output or error streams from an operating system command. OS services are better suited for this.
• For non-interactive server-side applications where precise process control and resource management are paramount.
• When complex inter-process communication or advanced process management is required.

Conclusion

The spawn command is a powerful and flexible feature within Uniface 10.4, providing a direct link to the underlying operating system. It simplifies tasks such as file management, launching external programs, and automating system-level operations. By understanding its mechanics, platform specificities, and applying best practices, developers can leverage spawn effectively and securely to enhance their Uniface applications. Remember to thoroughly test commands and implement robust error handling for a reliable user experience.