The OEMANAGER utiltiy is a command line tool which uses the Ant utility provided in the DLC installation to execute “tasks”. Some tasks are shortcuts to the TCMAN utility, though most tasks run built-in ABL code using the Progress Compile Tools (PCT) library. The OEMANAGER utility is deployed to each Progress Application Server (PAS) for OpenEdge instance as part of the CATALINA_BASE/bin directory which allows it to be tailored on a per-instance basis. The following sections demonstrate the overall usage including how to access the inline help and use the oemanager.properties configuration file to customize tasks.

Syntax

The OEMANAGER script is located in the CATALINA_BASE/bin directory of the PAS for OpenEdge instance you created. This is the syntax for the command:

oemanager[.sh|.bat] [tasks] [parameters]
tasks
Tasks include the following: query, startup, shutdown, inventory, status, stacks, flush, locks, users, add, close, refresh, reset, stop, trimsingle, trimall, trimidle, trimhttp.
To see the usage (help) information for the OEMANAGER command line utility, run the command without additional arguments:
oemanager[.sh|.bat]
The output is similar to the following:
     [echo] DLC Home: C:\Progress\OpenEdge
     [echo] OpenEdge Version: 12.8.0
     [echo]
     [echo] CLI utilities for monitoring and management of a PASOE instance.
     [echo] Tasks denoted with [RO] are read-only and do not impact operation.
     [echo]
     [echo] Usage Instructions:
     [echo]
     [echo]  TCMAN Shortcuts:
     [echo]
     [echo]  oemanager query    - Use TCMAN to query the PAS instance
     [echo]
     [echo]  oemanager startup  - Use TCMAN to start the PAS instance
     [echo]                       [OPTIONAL] timeout=300 - Time (seconds) to wait for a proper startup
     [echo]
     [echo]  oemanager shutdown - Use TCMAN to stop the PAS instance
     [echo]                       [OPTIONAL] timeout=300 - Time (seconds) to wait for a proper shutdown
     [echo]
     [echo]
     [echo]  Support Tools:
     [echo]
     [echo]  oemanager inventory - Bundle useful PAS instance files (as .zip) for support tickets
     [echo]
     [echo]
     [echo]  Status/Info:
     [echo]
     [echo]  oemanager status - [RO] Obtain MSAgent/connection status information for an ABL App
     [echo]                     [REQUIRED]  ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                     [OPTIONAL] basemem=819200 - Minimum memory threshold (bytes) to consider as 'unused' agent sessions
     [echo]
     [echo]  oemanager stacks - [RO] Obtain stack information for all MSAgents for an ABL App
     [echo]                     [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                     [OPTIONAL]    pid=[AGENT_PID]  - Limit stack information to a specific MSAgent process ID
     [echo]                     [OPTIONAL] sessid=[SESSION_ID] - Limit stack information to a specific ABL Session ID
     [echo]                                                      Requires specifying an MSAgent via pid=[AGENT_PID]
     [echo]
     [echo]  oemanager flush  - [RO] Flush the available deferred log buffer to agent log file
     [echo]                     [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]
     [echo]  oemanager locks  - [RO] Display database users and their table locks related to an MSAgent-Session
     [echo]                     This utilizes a single DBConnection; edit the 'locks' task in build.xml to add more as necessary
     [echo]                     Note: Only provides session data if using self-service DB connections for OE versions under 12.5
     [echo]                     [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                     [REQUIRED]     pf=[PF_NAME] - PF file to use for database connection(s)
     [echo]
     [echo]  oemanager users  - [RO] Alias for 'locks' task
     [echo]
     [echo]
     [echo]  Agent Management:
     [echo]
     [echo]  oemanager add     - Add (read: start) one new MSAgent for an ABL App
     [echo]                      [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]
     [echo]  oemanager close   - Perform a 'soft restart' of an ABL App (runs: status, flush + trimhttp + stop, status)
     [echo]                                       For this task the 'trimhttp' will be called with the termination option 1 (forced)
     [echo]                      [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                      [REQUIRED] webapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active client sessions
     [echo]                                  The given WebApp is expected to be associated with the provided ablapp name
     [echo]                      [OPTIONAL] sleep=1 - Sleep time in minutes after stop, prior to final 'status' output
     [echo]
     [echo]  oemanager reset   - Reset an aspect of each MSAgent for an ABL App
     [echo]                      [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                      [REQUIRED] resettype=stats [stats|logs]
     [echo]
     [echo]  oemanager stop    - Gracefully stop one or all MSAgents (+stacks output) for an ABL App
     [echo]                      [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                      [OPTIONAL] waitfinish=120000 - How long to wait (milliseconds) if the MSAgent is busy serving a request
     [echo]                      [OPTIONAL]  waitafter=60000  - Additional time to wait (milliseconds) before killing [hard stop] the MSAgent
     [echo]                      [OPTIONAL]        pid=[AGENT_PID] - Numeric process ID for a specific MSAgent to be stopped
     [echo]
     [echo]
     [echo]  Session Management:
     [echo]
     [echo]  Note: All trim actions listed below will write application stack information to a file.
     [echo]
     [echo]  oemanager trimsingle - Trim a single ABL Session (via the Agent Manager) for a specific MSAgent
     [echo]                         [REQUIRED]       ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                         [REQUIRED]          pid=[AGENT_PID]  - Numeric process ID of the MSAgent for context
     [echo]                         [REQUIRED]       sessid=[SESSION_ID] - Numeric ID for the ABL Session to be stopped
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]  oemanager trimall    - Trim all available ABL Sessions (via the Agent Manager) for each MSAgent for an ABL App
     [echo]                         Note: For any busy sessions considered stuck use 'trimhttp' with a specific Session ID
     [echo]                         [REQUIRED]       ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]  oemanager trimidle   - Trim only the IDLE ABL Sessions (via the Agent Manager) for each MSAgent for an ABL App
     [echo]                         Allows for manually scaling down an MSAgent which may have many unused ABL Sessions
     [echo]                         [REQUIRED]       ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]  oemanager trimhttp   - Trim one or all Client HTTP Sessions (via the Session Manager) for an ABLApp + WebApp
     [echo]                         Terminating a client HTTP session will also terminate its associated ABL Session
     [echo]                         [REQUIRED]       ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]                         [REQUIRED]       webapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active sessions
     [echo]                                           The given WebApp is expected to be associated with the provided ablapp name
     [echo]                         [OPTIONAL]       sessid=[SESSION_ID]  - Alphanumeric Client Session ID to be stopped
     [echo]                                           When no session ID provided, all available Client HTTP Sessions will be expired
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]  oemanager refresh    - Refresh ABL Sessions for each MSAgent for an ABL App
     [echo]                         Note: This will terminate all sessions using the 'finish+stop' option,
     [echo]                               which prepares the MSAgent to pick up available R-code changes.
     [echo]                               Use this only during a 'quiet period' for your application.
     [echo]                         [REQUIRED] ablapp=oepas2 - ABL Application name, defaulting to the instance name if not changed
     [echo]
     [echo]
     [echo] Current parameter values, override via command line or 'oemanager.properties':
     [echo]     scheme=http
     [echo]       host=localhost
     [echo]       port=8820
     [echo]     userid=tomcat
     [echo]     passwd=tomcat
     [echo]     ablapp=oepas2
     [echo]     webapp=
     [echo]     outdir=BIN [C:\OpenEdge\WRK\oepas2\bin]
     [echo]
     [echo] NOTE: The name of the ABLApp is case-sensitive!
     [echo]
     [echo] CATALINA_HOME: C:\Progress\OpenEdge\servers\pasoe
     [echo] CATALINA_BASE: C:\OpenEdge\WRK\oepas2
     [echo]
     [echo]
     [echo] See oemanager.README.md for more information

Note that some OEMANAGER tasks have optional and required parameters. For more information on the uses cases for the available tasks, see OEMANAGER use cases.

Set properties

All OEMANAGER tasks use a set of common parameters either derived from the local PAS instance, specified via the oemanager.properties file, or specified via the command line. The derived properties are from the appserver.properties and catalina.properties files in the conf folder. To summarize, the property order of precedence is as follows:
  1. Command line
  2. The oemanager.properties file
  3. Derived properties from the PAS instance (appserver.properties and catalina.properties files)

To override any property values, simply pass as property-name=value on the command line or uncomment the property name and set a default value within the oemanager.properties file (found in the bin directory of the PAS instance). Every time you run the utility, properties are picked up from the properties file (or command line) and automatically applied for every request made to the OpenEdge Manager web application.

The following example sets the scheme, userid, and passwd properties from the command line::
oemanager scheme=https userid=myuserid passwd=mypasswd
Note: If you change any parameters for a task but omit the task name itself, the command prints the usage instructions with those property changes reflected. In other words, you can do a real-time sanity check on your values to confirm everything is correct before executing.

Oemanager.log

All calls that the OEMANAGER utility makes to the underlying API are logged in the oemanager.log file (located in the bin directory of the PAS instance by default). The purpose of the log file is for assisting technical support should they need to know what commands were executed. No credentials are output to the log. The log is simply a record of commands (and the base URLs) with no sensitive data. The following is an excerpt showing the API calls logged after issuing the oemanager status command.

[2024-04-12T14:08:37.795-04:00] O.A.U.OEManagerConnection INFO: RUN OpenEdge\ApplicationServer\Cli\getStatus.r
[2024-04-12T14:08:37.798-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications
[2024-04-12T14:08:37.869-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/properties
[2024-04-12T14:08:37.911-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/agents/properties
[2024-04-12T14:08:37.951-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/metrics
[2024-04-12T14:08:37.988-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/agents
[2024-04-12T14:08:38.019-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/sessions
[2024-04-12T14:08:38.044-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/agents/15012/dynamicSessionLimit
[2024-04-12T14:08:38.085-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/agents/15012/threads
[2024-04-12T14:08:38.112-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/agents/15012/metrics
[2024-04-12T14:08:38.141-04:00] O.A.U.OEManagerConnection INFO: GET http://localhost:8820/oemanager/applications/oepas2/agents/15012/sessions

Note that multiple APIs can be called for a single task.

Change file output location

The default location for all output files is the CATALINA_BASE/bin folder though this can be changed through use of the outdir parameter. There are two names which may be used for pre-determined locations: BIN and TMP. The value BIN provides the mentioned default of CATALINA_BASE/bin, while TMP uses the CATALINA_BASE/temp directory. A full path may be provided to a location on the file system while relative paths are relative to the BIN location.

Troubleshooting notes

  • If you execute the oemanager status command, you may see the following message:
    [PCTDynRun] Unable to get application list from PASOE instance: Connection failure for host localhost port 8820 transport TCP. (9407)
    This error can be due to several issues:
    • The PAS instance is not started
    • A networking issue is preventing access to the host and port provided
  • If you execute the oemanager status command, you may see the following message:
    [PCTDynRun] Unable to get application list from PASOE instance: Management WebApp(s) Not Deployed
    This error is specifically due to the management webapps oemanager.war and/or manager.war not being deployed. To rectify this, make sure that oemanager.war is deployed and that the PAS instance is correctly configured and started.
  • You may see an error for invalid credentials:
    [PCTDynRun] Unable to get application list from PASOE instance: Invalid Credentials
    This error is specifically due to use of an incorrect username and/or password value.
  • A best practice is to leave the passwd blank in the oemanager.properties file and enter it on the command line. If you forget to enter it on the command line, you get a generic error that says:
    argument cannot be empty
  • If you leave the passwd blank in the oemanager.properties file (best practice) and enter an incorrect one on the command line, you may become locked out (after too many failed authentication attempts) and will see a message like this in the log file of the PAS instance:
    LockOutRealm - An attempt was made to authenticate the locked user [myuserid]

    To rectify this, wait five minutes or restart the PAS instance.