RunScriptFile: run Maximo database and presentation scripts from the SMP

One script, one command, actual database changes

runscriptfile executes a named Maximo change script against the database configured in the SMP. That can mean SQL, a DBC change script, an MXS presentation transaction file or another supported script type.

It is a useful companion to MXDiff: MXDiff generates presentation transactions; RunScriptFile can execute the resulting MXS through Maximo's screen-update handler.

This tool executes and commits changes. It is not a preview or a script validator. Confirm the target database and review the script, dependencies and recovery plan before running it. Use the maintenance conditions required by the particular change; being able to connect does not establish that a script is safe to run while Maximo is active.

The details below come from the supplied SMP's launchers and Java classes, including psdi.tools.RunScriptFile and psdi.tools.ScriptExecutionInfo. They have been inspected rather than executed against a live database for this article. An exact tested Maximo release is therefore not claimed.

Find the launcher

In this SMP, the files live under:

maximo/tools/maximo/internal/runscriptfile.bat
maximo/tools/maximo/internal/runscriptfile.sh
maximo/tools/maximo/internal/runscriptfile.xml

The batch and shell launchers move up one directory to tools/maximo, load the common environment, then invoke:

psdi.tools.RunScriptFile

Start in the internal directory when using these supplied launchers. Their relative paths depend on that working directory.

Help: two slightly different answers

On Windows:

cd C:\IBM\SMP\maximo\tools\maximo\internal
runscriptfile.bat -h

On a Linux installation with a functioning supplied shell launcher:

cd /opt/IBM/SMP/maximo/tools/maximo/internal
./runscriptfile.sh -h

The Java -h path prints:

Usage : -c<input directory name> -f<script file name> -h<help>

Running with no arguments prints a different usage line:

Usage : -c<input directory name> -f<script file name> -h<help> -x<debug mode>

Both Java paths exit with status 0 before loading the properties file or connecting to the database. The launcher's environment setup still happens first.

Unlike the MXDiff help quirk, this class explicitly handles -h. It also accepts -help, but with a catch: the parser only compares the first two characters, so -help matches the same -h branch. The help omitting -x does not mean debug mode is unimplemented.

All parsed command-line options

Attach values to their options. The parser takes each argument's first two characters as the option and the remaining text as its value:

Use:    -csitechanges -fMY_PRESENTATION_CHANGE
Avoid:  -c sitechanges -f MY_PRESENTATION_CHANGE

Option matching is case-insensitive, but that does not make Linux filenames or directory names case-insensitive. Repeated -c or -f arguments overwrite the earlier value; they do not create a list of scripts.

There are no parsed command-line options here for a database URL, username, password, arbitrary properties file, log directory, dry run, quiet mode or rollback. -q and -d are not this tool's flags. A bare -c or -f raises a missing-value error. Omitting -f entirely leaves the filename unset rather than selecting a safe default: always provide it for execution.

Where -c and -f look

For a compatible MXS file arranged like this:

tools/maximo/
  internal/
    runscriptfile.sh
  en/
    sitechanges/
      MY_PRESENTATION_CHANGE.mxs

run, from internal:

./runscriptfile.sh -csitechanges -fMY_PRESENTATION_CHANGE

The example filename is illustrative; it is not a supplied or tested change script. Replace it with your reviewed script basename.

The default directory is en/script, so a file stored there can be selected without -c:

./runscriptfile.sh -fMY_PRESENTATION_CHANGE

-c is a directory selection inside the tool's script layout, not a general absolute-path option. -c/tmp does not mean “run a file directly from /tmp”. Likewise, -f takes a basename rather than /tmp/file.mxs or file.mxs. The resolver adds extensions and also attempts Java-class lookup.

The root is derived from classpath resource lookup, with handling for a classes/ directory and a working-directory fallback. Retain the expected SMP layout and classpath instead of assuming that a script can be run from any copied directory.

Which file type wins?

The resolver first attempts to load a matching Java script class using the selected directory and basename. If that class is unavailable, the file lookup order is:

The database-specific branch checks Oracle, Microsoft SQL Server or DB2 from JDBC metadata. It does not try every database's SQL dialect. If the applicable database-specific file is absent, lookup continues with the later types.

A generic .sql takes priority over a matching .dbc or database-specific file in this implementation. Do not leave several unrelated files with the same basename and assume the extension you had in mind will win.

A CSV here means input compatible with the invoked loader, not any CSV export you happen to have. Similarly, an MXS file must contain compatible screen-update transactions. File extension support is not a guarantee that arbitrary contents are valid.

The dispatcher also checks seamless-upgrade state before executing several script types. Recognising a file is not, on its own, proof that its handler executed; inspect the log and verify the intended result.

Debug mode: -x still runs the script

./runscriptfile.sh -csitechanges -fMY_PRESENTATION_CHANGE -x

The Java parser prints:

-x option for Debug and L3

It sets psdi.tools.UpdateDB.debugMode to true. During initialisation, that causes the summary and SQL loggers to include queries. It also enables the runner's trace messages for the resolved root, directory and script name.

This is additional logging, not a debugger connection, a pause before execution or a dry run. The script still executes and commits. Some extra detail goes to the logs rather than appearing as a dramatic change in terminal output.

-fALL: batch execution, with sharp edges

The Java code recognises exact uppercase ALL as a special filename:

./runscriptfile.sh -csitechanges -fALL

This enumerates the selected en/<directory> folder, sorts its entries and runs each derived basename. The comparator has numeric ordering for matching Maximo V..._... version-style filenames and otherwise compares names lexically. This is filename ordering, not dependency analysis.

There are important limitations in the inspected loop:

• It takes the basename before the first dot in each entry's name.
• It does not first filter the entries to a clean list of supported regular script files.
• Two files sharing that basename can cause the same resolved script to be selected more than once.
• A name with no dot can fail during basename extraction; unrelated files and subdirectories are not harmless passengers.
• Each successfully executed script is committed separately. A later failure does not roll back earlier scripts as one batch.

Use a deliberately prepared script-only directory if you need batch mode. For a controlled one-off change, explicitly selecting one -f basename is easier to review.

The loop reopens a connection if a script closes it. After the script work, the runner also invokes EAuditFix.checkAndRepair, then commits and closes the connection. Its database work is therefore not necessarily limited to statements visibly present in your input file.

Properties, logs and success checks

The normal initialisation reads:

maximo/applications/maximo/properties/maximo.properties

The path is constructed relative to the expected tools/maximo working directory. The database connection comes from those properties; the command does not ask you to choose a database interactively.

The runner writes under tools/maximo/log using a primary log name shaped like:

<mxe.name>_RUNSCRIPT_<script basename>.log

mxe.name defaults to MXServer. A related warnings log is configured too, and audit repair can produce its own output. Preserve the logs before rerunning: the inspected runner opens its primary print stream with an ordinary file output stream, rather than guaranteeing a fresh timestamped filename on every invocation.

You may see:

RunScript complete: Successful

That message is logged before the final audit-repair and connection-cleanup work. Verify the complete log and resulting database or presentation state, rather than treating that line alone as final proof of success. The connection-failure path also returns without necessarily forcing a failing process exit, so exit status alone is insufficient.

The wrappers have their own opinions

The Java parser is only part of the journey. The supplied launchers differ:

The inspected shell wrapper also contains dirname %0 after cd ... %0 is not the shell's script-name variable. In the expected working directory it can resolve to . and still source commonenv.sh, but it does not reliably locate the launcher. An absolute path to that launcher does not fix its working-directory assumptions.

If you adapt a launcher for a Manage pod, preserve its correct environment and directory setup, point at the installed Java runtime, and forward arguments with quoted "$@". The MXDiff shell guide explains the general launcher translation; do not copy its paths unchanged because this tool lives in a different directory.

Accept spaces between options and values

Download maximo-spaced-args.sh and place it alongside runscriptfile.sh in tools/maximo/internal. 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 '-c -f' "$@" || exit "$?"
set -- "${MAXIMO_NORMALIZED_ARGS[@]}"

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

In a copy of the supplied launcher, change the shebang to Bash and insert the block immediately after it. Remove the old argument-reset and argument-capture/shift code completely. Keep its cd .. to reach tools/maximo, replace the dirname %0 environment-loading lines with source ./commonenv.sh . || exit "$?", and replace the final Java invocation with:

../java/jre/bin/java -Xmx5G \
  -classpath ".:./classes:$MAXIMO_CLASSPATH" \
  psdi.tools.RunScriptFile "$@"
exit $?

The . argument gives the supplied environment script its SMP-relative base rather than letting it interpret a tool option as its path. Continue launching from internal; the working-directory requirement still applies. The adapter changes argument syntax, not script lookup: -f remains a basename without an extension and -c remains the subdirectory under en.

With the integration in place:

./runscriptfile.sh -c sitechanges -f MY_PRESENTATION_CHANGE -x

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.

Before you call it done

Confirm the configured database, the selected basename and the file type actually resolved. Execute the reviewed change under the appropriate maintenance conditions, retain its logs, and verify the intended application or database result before repeating it elsewhere.

I Build Maximo. The command is short. The change still deserves a review.