Using REXX CALL to Invoke External Programs: An Architecture Note

Problem Statement

Many REXX scripts need to execute external utilities and process their results. The CALL statement is the built‑in mechanism for this, but its use introduces several architectural concerns: how to construct the command, how to capture output, how to interpret exit status, and how to mitigate security risks.

Requirements

• Interpreter compatibility: The design must work on IBM REXX, Open Object REXX, and other common implementations. Path resolution and exit code handling can vary.
• Deterministic behavior: The script should block until the external program completes, so the calling flow remains simple.
• Output capture: The ability to retrieve standard output into a REXX variable or stream it to a file.
• Exit status handling: The script must be able to detect success (typically _RC = 0) or failure.
• Security: User‑supplied or dynamic command fragments must be validated to prevent injection.
• Resource limits: Large output streams should not exhaust the REXX process memory.

Minimal Suitable Design

The simplest pattern uses CALL with the LIST keyword, which captures standard output into a variable and returns the exit code in _RC. The command string is constructed from environment variables or configuration data, ensuring that hard‑coded paths are avoided.

# REXX
/*  Example: Invoke an external utility and capture its output
    Environment variable: MY_CMD points to the executable path */

command = "%MY_CMD%" || "echo"  /* fallback to echo if not set */
args   = "Hello, world!"
output = ""

CALL command || " " || args LIST output

/* _RC holds the exit status */
IF _RC = 0 THEN
    SAY "Command succeeded: " output
ELSE
    SAY "Command failed (RC=" _RC "): " output

In this snippet:

• The command is assembled from a trusted environment variable MY_CMD or a default.
• Arguments are concatenated safely; if they come from user input, they should be quoted or escaped.
• Standard output is stored in output, and the exit status is checked via _RC.

Trust and Data Boundaries

Because CALL passes the command string to the underlying operating system, any unfiltered user input can lead to command injection. The design should therefore enforce:

• Command whitelist: Only allow a predefined set of executable names.
• Argument sanitization: Escape or quote arguments that may contain spaces, quotes, or special characters. REXX’s QUOTE function can help.
• Execution context: Run the command under a dedicated user account with the minimal required permissions.
• Environment isolation: Clear or set only the environment variables that the external program needs.

Operational Checks

To maintain reliability, the script should perform the following checks after each CALL:

• Exit code validation: Verify that _RC equals the expected value. A non‑zero value should trigger error handling or retry logic.
• Output size guard: If output exceeds a threshold (e.g., 10 MB), truncate or redirect to a file to avoid memory pressure.
• Logging: Record the command, arguments, exit status, and a snippet of the output for audit purposes.
• Timeout enforcement: If the external program might hang, consider wrapping the CALL in a timer or using an external watchdog.

Failure Modes

Failure	Cause	Mitigation
Non‑zero _RC	Command reports error	Check output for error message; retry or abort
Command not found	Invalid path or missing executable	Validate path against whitelist; log detailed error
Memory exhaustion	Large output captured into a variable	Use LIST to stream to a file; set size limit
Interpreter differences	Exit code or quoting rules vary	Test on target interpreter; adjust syntax

When the Design Must Change

• Asynchronous execution: If the external program takes a long time and the script needs to continue, switch to CALL without LIST and manage the process via OS utilities.
• Large streaming output: For logs or data dumps, redirect output to a file and process it incrementally.
• Interactive prompts: If the external program requires user input, use CALL with INPUT redirection or an automation tool.
• Privilege elevation: When the command must run as another user, invoke it via sudo or a wrapper script that handles authentication.

Verification Steps

1. Known command test: Run CALL 'echo Hello' LIST output and verify that output contains "Hello" and _RC equals 0.
2. Non‑existent command test: Run CALL 'nonexistentcmd' LIST output and confirm that _RC is non‑zero and output contains an error message.
3. Boundary test: Capture a large output (e.g., CALL 'yes' LIST output with a size limit) and ensure the script does not crash.

Limitations

• REXX’s CALL is synchronous; it blocks until the external command finishes. For high‑throughput scenarios, consider external orchestration.
• Exit status interpretation may differ: IBM REXX returns the program’s exit code in _RC, whereas some Open Object REXX builds may return a different mapping.
• Environment inheritance can cause side effects if the external program modifies environment variables; isolate the environment if necessary.

Practical Check

Deploy a small test harness that executes the example script and captures logs. Verify the logs contain the expected command, exit status, and a snippet of the output. Use this harness as part of CI to catch any regression in CALL handling.