Running MXDiff in a Maximo Manage pod

The tool is there. The launcher speaks Windows.

You want to compare two versions of a Maximo presentation XML and generate the transactions describing the changes. The supplied SMP has a launcher for that:

maximo/tools/maximo/screen-upgrade/mxdiff.bat

Useful on Windows. Less useful inside a Linux-based Maximo Manage pod.

In the supplied files, this directory contains mxdiff.bat but no equivalent mxdiff.sh. We need a shell launcher to invoke the same Java class. The comparison logic already exists; we are giving it a Linux front door.

What MXDiff compares

MXDiff here means psdi.webclient.upgrade.MXScreenDiff, the presentation comparison tool invoked by screen-upgrade/mxdiff.bat. It compares a baseline presentation extract with a modified extract and writes a transaction file describing the differences.

Keep the direction straight: base is the starting point, modified is the intended result. Reversing them asks for a different set of changes.

Help: -h

To display the supplied tool's usage text, run:

./mxdiff.sh -h

After its startup banner, the supplied class prints:

Usage : -b<file> Baseline 6.x Extract File (baseline.xml)
        -f<file> Folder name containing 6.x Extract Files (baseline.xml)
        -m<file> Modified 6.x Extract File (mxversion.xml)
        -t<file> Transaction File (transactions.xml)
        -q Quiet
        -d Debug Mode

There is a catch: -h works by reaching the unknown-option handler, rather than a dedicated help case. The Java tool exits with status 1 after printing usage, so a shell or automation job can report failure even though it displayed the help successfully. The listed -f option has a separate implementation problem, explained below.

The other options: folders, quiet mode and debugging

The supplied tool's usage text also lists three options beyond the main comparison arguments:

The supplied class advertises -f, but does not implement it in its argument parser. Its parser handles -b, -m, -t, -q and -d; passing -f/tmp takes the usage/error path. Running ./mxdiff.sh -h prints this help, including -f, but -h itself is not a dedicated parsed help option: it reaches the unknown-option handler, which prints usage and exits with status 1. The help listing therefore does not prove that every advertised option is implemented.

Instead, the supplied implementation checks whether the -b path is a directory. If it is, it scans its immediate files for .xml extracts with supported document roots, including presentation, presentationset, systemlib and mobileapp-cdc. For a baseline directory, use:

./mxdiff.sh \
  -b/tmp/mxdiff/baselines \
  -m/tmp/mxdiff/modified.xml \
  -t/tmp/mxdiff/changes.mxs

Keep baseline extracts in their own directory. Pointing -b at a general /tmp folder can also pick up modified extracts or other XML files, so it is a poor choice for a baseline collection. The scan is not recursive. This behaviour comes from the supplied class; check your version if its implementation differs.

-q is parsed and sets the comparison instance's verbose flag to false. That suppresses selected verbose Logger.info calls, rather than silencing the whole program. The startup banner, Java version guidance and Processing Complete. message are printed independently and remain visible. Some other messages are also outside the verbose checks. If the enabled logging configuration or comparison inputs did not produce those verbose messages in the first place, the screen output can look unchanged. It is a flag with no value attached:

./mxdiff.sh -bbase.xml -mmodified.xml -tchanges.mxs -q

-d is also parsed: it sets the static DEBUG flag to true. In the supplied class, that flag gates a console diagnostic in the addElement path. It does not globally enable debug logging or print every comparison step. If the comparison does not reach that diagnostic branch, enabling it can leave the screen output unchanged:

./mxdiff.sh -bbase.xml -mmodified.xml -tchanges.mxs -d

Why does the screen output look the same?

Neither flag changes every line printed by the tool. There are separate output paths: direct console printing and messages sent through the configured logger.

For -q, a visible difference requires the normal run to emit one of the verbose messages through a logger configured to show it. Depending on the logging configuration, those messages may go to a log file, appear on the console, or be filtered out. Quiet mode does not mean “print nothing”.

For -d, the comparison must reach the specific guarded element-addition diagnostic. A comparison that only changes existing attributes, for example, need not produce that extra output. Debug mode does not mean “show everything”.

An unchanged terminal display therefore does not prove that the flags were ignored. In this supplied implementation, both are parsed; the particular comparison and logging configuration determine whether you see a difference.

These findings come from inspecting the supplied Java class's argument parser and flag references, rather than a live comparison of console output. Neither flag replaces the input or transaction-output arguments. The shell launcher already forwards all these options through "$@", so no script changes are needed. Use the native attached-value syntax for -b, -m and -t.

The class's built-in usage text calls these baseline and modified “6.x Extract” files and gives transactions.xml as its default transaction filename. That is historical wording in the supplied tool, not evidence that every modern XML document is suitable input. Use compatible presentation extracts and inspect the result.

The -t option lets us name the output changes.mxs. The extension does not turn it into a shell script or apply anything: it is the XML transaction output from this comparison. Do not treat it as interchangeable with every other Maximo script format simply because it ends in .mxs.

Windows and Linux, side by side

The original mxdiff.bat is a small wrapper around the Java tool:

@ECHO OFF
 
SETLOCAL
 
call ..\internal\commonEnv.bat
 
@..\..\java\jre\bin\java -classpath ..\classes;%MAXIMO_CLASSPATH% psdi.webclient.upgrade.MXScreenDiff %1 %2 %3 %4

Here is how its working lines translate to the shell launcher below. The shell column shows the corresponding lines; the complete runnable script follows the table.

The important classpath difference is easy to miss: Windows separates entries with a semicolon; Linux uses a colon. Changing the filename from .bat to .sh alone will not do it.

Download the shell launcher

Download mxdiff.sh and place it in the pod's tools/maximo/screen-upgrade directory alongside the existing tool files. It requires the Maximo classes and libraries already installed there; it is not a standalone replacement for IBM's Java tool.

The rewrite is:

#!/usr/bin/env bash
 
# Determine the directory this script resides in.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 1
 
# Load the common environment.
source "${SCRIPT_DIR}/../internal/commonEnv.sh" || exit "$?"
 
# Execute MXScreenDiff.
"${SCRIPT_DIR}/../../java/jre/bin/java" \
    -classpath "${SCRIPT_DIR}/../classes:${MAXIMO_CLASSPATH}" \
    psdi.webclient.upgrade.MXScreenDiff \
    "$@"

The launcher uses the bundled Java runtime and internal/commonEnv.sh, matching the working pod version. It uses : as the Linux classpath separator and quoted "$@" to forward arguments. Run it directly or with bash mxdiff.sh; sh mxdiff.sh bypasses its Bash shebang.

SCRIPT_DIR anchors the Java executable, environment wrapper and tool classes to the launcher. The script itself does not change the caller's working directory, so relative -b, -m and -t paths resolve from where you run it. Absolute paths work too. The environment wrapper must initialise MAXIMO_CLASSPATH correctly for your installation and invocation directory.

Run the comparison in the pod

Choose a Manage administrative or tools container that actually contains the SMP classes, environment script and Java runtime. Not every running application container necessarily includes them. Use your deployment's real namespace, pod and container names when opening its terminal.

For an installation at /opt/IBM/SMP/maximo, the following illustrates the commands inside that container:

cd /opt/IBM/SMP/maximo/tools/maximo/screen-upgrade
chmod +x mxdiff.sh
mkdir -p /tmp/mxdiff

Put the compatible baseline and modified XML extracts at /tmp/mxdiff/base.xml and /tmp/mxdiff/modified.xml, then run:

./mxdiff.sh \
  -b/tmp/mxdiff/base.xml \
  -m/tmp/mxdiff/modified.xml \
  -t/tmp/mxdiff/changes.mxs

You can also compare files relative to your current directory, for example from the directory containing the XML extracts:

/opt/IBM/SMP/maximo/tools/maximo/screen-upgrade/mxdiff.sh -bbase.xml -mmodified.xml -tchanges.mxs

The supplied argument handling expects the value attached to its option: -b/path/file.xml, not -b /path/file.xml. Quote the whole argument for paths containing spaces:

./mxdiff.sh \
  "-b/tmp/mxdiff/base presentation.xml" \
  "-m/tmp/mxdiff/modified presentation.xml" \
  "-t/tmp/mxdiff/presentation changes.mxs"

The launcher above forwards the native syntax unchanged. To accept separated options and values, add the explicit adapter integration in the next section.

Use a writable directory for the generated file. If the tool directory is read-only, do not overwrite the image's files: use your deployment's supported tools environment or writable SMP copy with the same directory layout. Save shell files with Unix LF line endings.

Accept spaces between options and values

Download maximo-spaced-args.sh and place it alongside mxdiff.sh in tools/maximo/screen-upgrade. Back up the launcher before editing it. The adapter guide explains the helper; here we can name the value-taking options explicitly instead of using auto.

Use this injection block before the launcher reads or shifts arguments:

SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) || exit 1
source "$SCRIPT_DIR/maximo-spaced-args.sh" || exit "$?"
maximo_normalize_args '-b -m -t' "$@" || exit "$?"
set -- "${MAXIMO_NORMALIZED_ARGS[@]}"

Only those listed options consume a following value. Boolean switches -q and -d pass through unchanged. Use the lowercase spellings shown: the helper's explicit matching is case-sensitive, even where Java accepts other cases.

Use the Bash launcher shown above. It already forwards arguments using quoted "$@", so its Java command needs no change. Add the block after its existing SCRIPT_DIR assignment, before environment setup. Do not add -f: the inspected MXDiff parser does not implement that advertised option.

With the integration in place:

./mxdiff.sh -b /tmp/mxdiff/base.xml -m "/tmp/mxdiff/modified presentation.xml" -t /tmp/mxdiff/changes.mxs

The example illustrates syntax, not a verified Maximo execution. Spaced values become attached arguments before Java receives them; already-attached values still work. Quote values containing spaces. Missing, empty or dash-leading separate values are rejected before Java starts; attach dash-leading values directly to their option.

Run the launcher directly or with bash, never sh, because the helper uses Bash arrays. Save edits with LF line endings. Before invoking the real tool, temporarily insert the following immediately after set -- to check the normalized arguments without executing Java:

printf 'Argument: <%s>\n' "$@"
exit 0

Use harmless sample arguments, then remove those two diagnostic lines when finished. Preserve quoted "$@" in the final Java command; otherwise later shell splitting undoes the helper's work. The adapter has shell-level tests, but this tool integration has not been executed against Maximo.

Review the transaction file

After the comparison, check that changes.mxs exists and inspect its contents. Confirm that it contains the intended presentation changes, particularly where controls were moved, removed or given new IDs.

Generating transactions and applying them are separate operations. Review the matching screen-upgrade apply tool and its requirements before using the output, then validate against a representative non-production presentation. The comparison does not prove that applying those transactions to a different starting version will produce the desired screen.

Copy the output out of the pod or onto persistent storage before the pod is replaced. /tmp is a convenient working directory, not an archive.

If it refuses to run

• Java is missing: verify that ../../java/jre/bin/java exists relative to the launcher in your tools container. This version uses that bundled runtime, rather than JAVA_HOME or PATH.
• The class cannot be loaded: verify tools/maximo/classes, the environment script and the libraries referenced by MAXIMO_CLASSPATH.
• An input cannot be found: resolve relative paths from your invocation directory, or use absolute container paths. A Windows host path is not a pod filesystem path.
• The tool prints usage instead of comparing: check the attached -b, -m and -t values.
• The output is unexpected: verify the base/modified direction and the compatibility of the extracts, then inspect control IDs and the generated transactions.

I Build Maximo. Occasionally, I build the missing launcher first.