ConfigDB: apply Maximo database configuration changes from the SMP

Saved the configuration. Now change the database.

Saving a change in Database Configuration and applying that change are separate steps. ConfigDB is the SMP command-line utility for applying pending database configuration changes.

The supplied launcher executes changes by default. Running it without arguments is not a help request or a preview.

This guide is based on inspection of the supplied launchers and Java bytecode for psdi.configure.ConfigDB and psdi.configure.CommonShell, alongside the IBM documentation linked below. The argument parser and setup branches have been inspected; no configuration has been executed against a live database. No exact tested Maximo release is claimed.

Find the launcher

In the supplied SMP, both launchers live directly under tools/maximo:

maximo/tools/maximo/configdb.bat
maximo/tools/maximo/configdb.sh

They invoke:

psdi.configure.ConfigDB

Start in tools/maximo. Unlike RunScriptFile, this launcher does not live in the internal directory. Its Java executable, environment script and properties path depend on the expected working directory.

What the launcher actually asks for

The supplied Windows launcher's Java command is:

@..\java\jre\bin\java %MEMORY_ARGS% -classpath %MAXIMO_CLASSPATH% psdi.configure.ConfigDB -l -e -r -k..\..\applications\maximo\properties %1 %2 %3 %4 %5 %6

The shell launcher invokes the same class with the same built-in flags and the corresponding forward-slash properties path.

These arguments are already present before anything you add at the command line. You do not need to supply -e to make the normal launcher execute.

Likewise, adding only -l does not turn this launcher into a preview: its built-in -e is still there. Do not assume that an extra option cancels one embedded in the script.

Before running it

Review the pending configuration changes and confirm that this SMP's properties identify the intended database. Have a database backup and a recovery plan appropriate to the changes.

IBM's Maximo 7.6.1.2 command-line configuration procedure requires shutting down the application server and waiting one minute for its session timestamp to expire before running ConfigDB. It places the command in tools/maximo and the troubleshooting logs under tools/maximo/log.

For Manage, use the maintenance procedure for your deployment. A terminal in a tools container does not establish that application instances connected to the database have stopped. IBM's Manage database update procedure also requires stopping the application server before running the utility.

The offline command-line procedure is separate from applying eligible changes through the application's live configuration facilities. Do not use the existence of those facilities as permission to run this command against an active environment.

Run the configuration

On Windows, using an illustrative installation path:

cd C:\IBM\SMP\maximo\tools\maximo
configdb.bat

On Linux, with a functioning supplied shell launcher:

cd /opt/IBM/SMP/maximo/tools/maximo
./configdb.sh

Replace those paths with the actual SMP location. In a Manage tools environment, confirm that the required classes, libraries, runtime and properties are available there.

The default properties filename documented by the launcher is maximo.properties. Its embedded -k points at:

maximo/applications/maximo/properties/maximo.properties

Do not infer the database target from the pod name, terminal title or directory name. Check the configured connection before execution.

Options verified in the Java classes

ConfigDB.main splits each argument into a two-character option and the remaining value, then stores it in a HashMap. CommonShell.setup handles the shared connection, properties and logging options; ConfigDB.endSetupInstance handles the additional flags. These options are implemented as well as documented in the launcher comments.

Attach values to their options: use -oconfigdb-reviewed-change.log, not -o configdb-reviewed-change.log. The parser does not consume the next argument as a value. Bare -a, -d, -f, -k, -o, -p and -u produce explicit missing-value errors during shared setup. Arguments shorter than two characters fail during substring extraction.

Option comparisons are case-insensitive, but the map keys are case-sensitive. Repeating an identically cased option replaces its earlier value, so an appended -k overrides the launcher's earlier -k. Avoid mixing cases for repeated options: -k and -K are separate map entries, and setup iterates the map rather than preserving command-line order.

For example, to request a recognisable log filename:

configdb.bat -oconfigdb-reviewed-change.log

./configdb.sh -oconfigdb-reviewed-change.log

These commands still execute the configuration and request restoration, because the launcher's built-in flags remain present. The filename is illustrative, not output from a tested run.

The launcher comments claim maximo fallbacks for the username and password. The inspected CommonShell.setupFromPropfile instead reads mxe.db.user and mxe.db.password with empty-string defaults and validates the resulting values. Do not rely on the comment's fallback account. Verify the configured credentials and required permissions; prefer properties over exposing passwords in shell history or process arguments.

Help: a verified early exit

From the expected tools/maximo working directory:

configdb.bat -h

./configdb.sh -h

The Java help branch prints:

Usage : -f<properties filename> -d<output directory> -o<output filename> -a<db alias> -u<username> -p<password> -l -e -r -z -h<help>
 
Also see javadocs.

It then calls System.exit(0) before setup or process. This exits before properties loading or database connection, even though the wrapper has already supplied -e. Environment setup and the Java startup banner still happen first.

-help also reaches this branch because only its first two characters, -h, are compared. It is not a separately parsed long option. A malformed earlier argument can still fail before the loop reaches help.

The help omits the implemented -k option and lists -z without explaining it. The launcher comments are not the complete option list either.

Additional flags and parser traps

These are specialised upgrade/text-search controls, not general troubleshooting or preview switches. Their parsing and setup effects are verified here; their full operational workflows have not been tested.

Boolean options are enabled by their presence, not by interpreting an attached value. -efalse still enables execution, and -rfalse still requests restoration. There is no parsed negative form to cancel the wrapper's -e or -r.

Unknown options are silently ignored by these setup handlers. They do not force help or stop execution. Passing an invented flag such as --help creates an unrecognised -- key and does not reach the -h branch. Through the standard wrapper, the built-in execution arguments remain active. Use the verified -h spelling.

-r: restore tables, not roll back the run

The launcher describes -r as calling psdi.configure.RestoreFromBackup immediately after ConfigDB ends without error. It refers to restoring data from the temporary backup tables associated with database configuration. It does not mean “roll back if anything goes wrong”, and it is not a substitute for a database backup.

The comments explicitly warn that data in XX-prefixed temporary tables sometimes needs modification before restoration. IBM's command-line procedure describes removing -r from the batch launcher for that workflow and restoring later when required.

Leaving -r off your command line does not disable restoration. It is already inside the supplied launcher. A deliberately reviewed launcher change is needed if your procedure requires a separate restore stage.

Do not remove it casually to get past a failure. If tables were rebuilt, a run without restoration can leave required data restoration outstanding. Follow the version-specific restore and backup-table cleanup procedure before restarting normal use or attempting another configuration.

The wrappers have their own opinions

As with RunScriptFile, the shell or batch wrapper is part of the behaviour:

The shell wrapper contains:

pathToScript=`dirname %0`
. $pathToScript/commonenv.sh

%0 is batch syntax, not the shell's script-name variable. From the expected directory this can resolve to . and find the environment script, but it does not reliably locate the launcher. Calling the wrapper by absolute path does not repair its other relative paths.

Its unquoted argument expansion can also split values containing spaces after you have quoted them at the command line. Use simple paths with the supplied wrapper, or review an adapted launcher that preserves arguments with "$@" and establishes the required working directory.

The MXDiff shell guide explains the general Windows-to-Linux translation. ConfigDB already has a shell launcher in this SMP, so check it before creating another. Its directory layout and maintenance requirements differ from MXDiff's.

Both ConfigDB files also contain a commented DB2DBDFT setting for DB2 installations. It is not active configuration as supplied. Follow your database-specific setup rather than uncommenting a sample database name unchanged.

Accept spaces between options and values

Download maximo-spaced-args.sh and place it alongside configdb.sh in tools/maximo. 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 '-a -d -f -k -o -p -u' "$@" || exit "$?"
set -- "${MAXIMO_NORMALIZED_ARGS[@]}"

Only those listed options consume a following value. Boolean switches -h, -l, -e, -r, -g and -z 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. Replace the dirname %0 environment-loading lines with source ./commonenv.sh . || exit "$?". Keep the existing JVM memory options and built-in configuration flags, replacing the final invocation with:

../java/jre/bin/java $MEMORY_ARGS \
  -classpath ".:./classes:$MAXIMO_CLASSPATH" \
  psdi.configure.ConfigDB \
  -l -e -r -k../../applications/maximo/properties "$@"
exit $?

Here $MEMORY_ARGS retains the supplied wrapper's word splitting for its JVM option list; application arguments use quoted "$@". The . argument gives the supplied environment script its SMP-relative base rather than a tool option. Continue launching from tools/maximo. The adapted launcher still executes configuration and requests restoration by default. The helper does not add a preview mode.

With the integration in place:

./configdb.sh -o "configdb reviewed change.log"

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.

Logs and completion checks

The launcher documents the normal log directory as:

maximo/tools/maximo/log

With -l enabled, its comments describe the default filename as ConfigDB plus a timestamp and .log. The -d and -o options select the directory and filename respectively.

Review the complete configuration output and any restoration output. Confirm that the pending changes were applied and that any required data restoration completed before following the restart procedure. Preserve the logs with the change record.

If it fails, investigate the first relevant error and the resulting database state before rerunning. Do not assume that a failed configuration left everything untouched, or manually remove temporary tables just because another run objects to them.

Useful first checks are the configured database, connection permissions, application shutdown state, available database resources, and whether the logs identify a configuration failure or a restoration failure. Those are different stages and can need different recovery steps.

Before you call it done

Check the intended configuration and restored data, retain the logs, then restart using the procedure for that environment and verify the affected application behaviour.

I Build Maximo. Saving the field was the easy part.