You can extend TCMAN by adding your own actions to the built-in actions of the TCMAN utility. You implement actions as UNIX shell scripts, Windows batch files, or Windows PowerShell scripts. Customizing TCMAN with your own actions allows you to unify all of your administrative tasks under a single utility.

File name format

Name your TCMAN action scripts using the following convention:

action_nameCmd{.sh | .bat | .ps1}

where file name extensions .sh, .bat, and .ps1 are used for UNIX scripts, Windows batch files, and PowerShell scripts respectively.

UNIX action scripts

UNIX action scripts must be executable. That is, the file must have execution permissions for the current user. Each script must exit with a zero (0) status when successful, or a positive non-zero value to indicate an error.

When the action script is in the core server's bin directory ($CATALINA_HOME/bin), it is available to administrators of any instance. When the action script is in an instance's bin directory ($CATALINA_BASE/bin), it is only available to administrators of that instance.

The search order is:
  1. $CATALINA_BASE/bin
  2. $CATALINA_HOME/bin

Windows batch and PowerShell action scripts

On Windows, action scripts can be either DOS batch scripts (.bat) or PowerShell scripts (.ps1). Batch scripts should return zero (0) for success, or a positive non-zero integer to indicate an error level. Powershell scripts should return \$true for success or \$false to indicate an error.

When the action script is in the core server's bin directory ($CATALINA_HOME/bin), it is available to administrators of any instance. When the action script is in an instance's bin directory ($CATALINA_BASE/bin), it is only available to administrators of that instance.

If you have both batch and PowerShell scripts, TCMAN gives precedence to batch files. The search order is:
  1. $CATALINA_BASE/bin/action_nameCmd.bat
  2. $CATALINA_BASE/bin/action_nameCmd.ps1
  3. $CATALINA_HOME/bin/action_nameCmd.bat
  4. $CATALINA_HOME/bin/action_nameCmd.ps1

Command-line Syntax

You invoke an action script by specifying the action-name segment of a script's file name in a TCMAN command line.

tcman.sh action-name [general_options] [ action-name_options]
Note: You do not include the Cmd.extension portion of the file name on the TCMAN command line.

TCMAN first looks for action scripts in the instance ($CATALINA_BASE/bin) and then in the core server ($CATALINA_HOME/bin). When it finds the action script, TCMAN passes all command line options and parameters during execution.

Example

The following command line runs a script file named viewCmd.sh and passes the -v option and the logs/catalina.out argument.

tcman.sh view -v  logs/catalina.out

Notes

  • When TCMAN does not recognize action-name as one of the built-in actions, it looks for an action script . If the specified action is not a built-in action or external action script it will exit with an error.
  • When the external action script exits, TCMAN uses its return status to either issue an error or to exit with success. Therefore, extension action scripts should always return a specific value according to the platform type.
  • Before executing an external action script, TCMAN exports these environment variables for consumption by the action script file:
    • JAVA_HOME : the root directory of the JAVA JDK (optional)
    • JRE_HOME : the root directory of the JAVA JRE (optional)
    • CATALINA_HOME : the root directory of where PAS was installed
    • CATALINA_BASE : the root directory of the PAS instance being managed (can be the same as CATALINA_HOME)
    • CATALINA_TMPDIR : the temporary file directory for temp files
    • CATALINA_PID : the file where the PAS process-id is stored
    • tcman_osshell : The name of the OS and command line shell TCMAN is running in
    • tcman_instancebase : the name of the new instance base directory when executing a create action
    • tcman_httpport : the HTTP network port command line option (-p)
    • tcman_httpsport : the HTTPS network port command line option (-P)
    • tcman_cfghttpport : the current instance's configured HTTP network port
    • tcman_cfghttpsport : the current instance's configuredHTTPS network port
    • tcman_cfgshutport : the current instance's shutdown network port (can be -1 if there is no network shutdown port)
    • tcman_alias : the instance's alias name
    • tcman_type : the type of instance (home, service (on Windows), instance)
    • tcman_secmodel : the security model to apply ( default, production, or development )
    • tcman_umask : the UNIX umask to use when creating new directories and files
    • tcman_verbose : the state of the TCMAN -v command line option
    • tcman_debug : The state of the TCMAN -g command line option