Running Operating System Commands in Uniface 10.4

Introduction

Uniface 10.4 allows you to execute operating system commands directly from ProcScript using the built‑in COMMAND and COMMANDOUT operations exposed by an OS service signature.

This is useful for tasks like calling shell scripts, batch files, or external tools, while still keeping the main business logic in your Uniface application.

What OS commands in Uniface are

Uniface provides a special service type often called something like OS that exposes two default operations: COMMAND and COMMANDOUT.

These operations are invoked using the activate ProcScript statement and pass a command string to the underlying operating system shell.

Under the hood, Uniface forwards the command to the OS and reports success or failure back to your ProcScript via the usual $status and $procerror variables.

If the OS command itself is invalid, Uniface raises an activation error and sets $status and $procerror to -150.

Maximum command length limits

When passing commands, you must respect the maximum length supported by the target operating system.

Typical limits in the Uniface 10.4 documentation are:

Windows: up to 8K
Unix/Linux: up to 4K
IBM iSeries: up to 512 bytes per command string

If you build a very long command line that exceeds these OS limits, the command execution will fail before it reaches your actual tool or script.

In practice this means you should keep commands short, avoid inlining huge argument lists, and consider using wrapper scripts when you need complex behavior.

Synchronous execution with COMMAND

By default, calling COMMAND is synchronous, which means Uniface waits until the operating system finishes the command before your ProcScript continues.

This is appropriate for short‑running tasks where your business logic depends on the result, for example building a file and then immediately importing it into the application.

A simple pattern looks like this in ProcScript:

variables
   string vCmd
endvariables

vCmd = "dir /B" ; or "ls" on Unix-like systems
activate "OS".COMMAND(vCmd)

if ($status < 0)
   ; handle error, e.g. log $status and $procerror
endif

This code activates the COMMAND operation on the OS service with a single string parameter that contains the OS command to execute.

Error handling should always inspect $status and $procerror to detect both activation issues and OS‑level problems.

Capturing output with COMMANDOUT

While COMMAND is fine when you only care that the command ran, COMMANDOUT is intended for scenarios where you need to capture and process the text output from the OS command.

Typical examples are parsing directory listings, reading the output of a custom tool, or integrating with scripts that return machine‑readable text.

A common pattern uses one parameter for the command and another for the returned output string, similar to the following conceptual example:

variables
   string vCmd
   string vOut
endvariables

vCmd = "mytool --list"
activate "OS".COMMANDOUT(vCmd, vOut)

if ($status >= 0)
   ; process vOut, e.g. parse lines or tokens
else
   ; handle error condition
endif

The exact signature of COMMANDOUT depends on how the OS service signature is defined in your model, but the core idea is that the operation returns the OS output into a ProcScript variable.

From there you can split the string, validate content, or log it as part of your application diagnostics.

Asynchronous execution with /async

Sometimes you want to fire off a command and not wait for completion, for example starting a long‑running batch process or a background script.

Uniface supports this by allowing the /async switch on the activate statement, which makes the OS command execution asynchronous.

A typical example looks like this:

activate/async "OS".COMMAND("at -fm myscript")

Here the activate/async qualifier tells Uniface to start the command and immediately continue ProcScript execution without waiting for the OS command to finish.

This approach is useful when the command does not have to return a result to the current user interaction and will instead log or report success asynchronously.

Non‑interactive nature of OS services

Uniface OS services are not interactive, which means they cannot reliably host applications that expect to read from or write directly to a terminal UI or prompt the user.

Because of that, the documentation explicitly recommends using the spawn ProcScript statement when you need to run truly interactive applications.

Commands executed via COMMAND or COMMANDOUT should therefore be written to run unattended, using arguments and configuration files instead of interactive prompts.

If your current workflow starts interactive tools, consider wrapping them in non‑interactive scripts that read inputs from files or environment variables.

Error handling and diagnostics

Whenever you call COMMAND or COMMANDOUT, it is important to check both $status and $procerror after the activation.

If the OS command is invalid or Uniface cannot activate the operation, $status and $procerror are set to -150, which tells you there was an activation‑level problem rather than a business error in your script.

For production systems, you should log at least the command string, $status, $procerror, and any returned text, so you can troubleshoot failures on the server.

In multi‑platform environments this logging is especially useful, because command length limits and shell behavior can differ significantly between Windows, Unix/Linux, and iSeries.

Best practices and recommendations

Design your OS commands to be short, deterministic, and non‑interactive, delegating complex logic to external scripts that you version‑control alongside your Uniface application.
Prefer COMMANDOUT when you need structured output and integrate the parsing logic into your ProcScript, keeping a clear contract between the shell script and the Uniface component.
Use synchronous calls for user‑critical operations and asynchronous activation for background jobs that do not affect the current transaction or UI flow.
Always validate $status and $procerror and handle the -150 case explicitly so that you can distinguish between OS‑level issues and functional errors in your own ProcScript