The following section covers specific cases of when and how to use the tasks listed via the inline help as seen in OEMANAGER tasks.

Obtain runtime data

The following tasks are read-only and simply report data from a running Progress Application Server (PAS) for OpenEdge instance.

  • status — This is the most-used task for monitoring a PAS instance. It produces comprehensive output which is reminiscent of the old ASBMAN utility but formats and displays more relevant data meant for the PAS server architecture. In addition to statistics and metrics (when enabled) the output shows the current state of all MS Agents and their ABL sessions, and HTTP connections to the PAS instance.
  • locks / users — This task uses one or more connected databases (specified via a .pf file) to correlate any table locks to ABL code running in the application. This task utilizes information about current requests to an MS Agent, stack information, and session data to create an end-to-end picture of which user may be active in a table.
  • flush — When deferred logging is enabled, flush forces any current data in the deferred log buffer (up to the configured number of lines) to be flushed to the named log file. See Use deferred logging in PAS for OpenEdge for instructions on configuration and enablement of the deferred logging feature.
  • stacks — Reports the current stack information for a given ABL application, creating a unique file for each MS Agent. This data is only visible for MS Agents which are currently busy executing ABL code. Note that all tasks which terminate sessions or MS Agents automatically generate this same stack information.

Example: the OEMANAGER status task

The status task of the OEMANAGER utility is one of the most useful tasks and provides information about the PAS instance. Output is displayed on the console and is also written to a text file so you can refer to it later. The text file can be found in the bin directory of the PAS instance and the filename is timestamped (for example, status_<instance>_YYYY-MM-DDThh_mm_ss.ss-zz_zz.txt) and placed in the bin directory of the PAS instance by default.

The following is sample output from executing oemanager status:

Buildfile: C:\OpenEdge\WRK\oepas2\bin\oemanager.xml

status:
     [echo]
     [echo] DLC Home: C:\Progress\OpenEdge
     [echo] OpenEdge Version: 12.8.0
[PCTDynRun] Starting output to file: C:\OpenEdge\WRK\oepas2\bin\status_oepas2_2024-04-12T14_08_37.780-04_00.txt ...
[PCTDynRun]
[PCTDynRun] Utility Runtime: 12.8.0.0.1207
[PCTDynRun] Report Executed: 2024-04-12T14:08:37.797-04:00
[PCTDynRun]  PASOE Instance: http://localhost:8820
[PCTDynRun]
[PCTDynRun] ABL Application Information [oepas2 - v12.8.0 ( 2023-12-21 )]
[PCTDynRun]     WebApp: ROOT
[PCTDynRun]       APSV: ENABLED
[PCTDynRun]       SOAP: ENABLED
[PCTDynRun]       REST: ENABLED
[PCTDynRun]        WEB: ENABLED
[PCTDynRun]
[PCTDynRun] Manager Properties
[PCTDynRun]             Maximum Agents:           2
[PCTDynRun]             Minimum Agents:           1
[PCTDynRun]             Initial Agents:           1
[PCTDynRun]     Max. Connections/Agent:         200
[PCTDynRun]     Max. ABLSessions/Agent:         200
[PCTDynRun]         Idle Conn. Timeout:     300,000 ms (00:00:05:00.000)
[PCTDynRun]       Idle Session Timeout:   1,800,000 ms (00:00:30:00.000)
[PCTDynRun]         Idle Agent Timeout:   1,800,000 ms (00:00:30:00.000)
[PCTDynRun]      Idle Resource Timeout:           0 ms (00:00:00:00.000)
[PCTDynRun]         Conn. Wait Timeout:       3,000 ms (00:00:00:03.000)
[PCTDynRun]       Request Wait Timeout:      15,000 ms (00:00:00:15.000)
[PCTDynRun]     Initial Sessions/Agent:           2
[PCTDynRun]     Min. Avail. Sess/Agent:           1
[PCTDynRun]
[PCTDynRun] > Agent PID 15012: AVAILABLE
[PCTDynRun]     Est. Agent Lifetime: 00:00:00:07.499
[PCTDynRun]     DynMax ABL Sessions:          200
[PCTDynRun]      Total ABL Sessions:            2
[PCTDynRun]      Avail ABL Sessions:            2
[PCTDynRun]        Open Connections:            1
[PCTDynRun]         Overhead Memory: 13,907 KB
[PCTDynRun]
[PCTDynRun]     SESSION ID      STATE           STARTED                         LIFETIME          SESS. MEMORY     ACTIVE MEM.   REQUESTS       BOUND/ACTIVE CLIENT SESSION
[PCTDynRun]                4    IDLE            04/12/2024 14:08:30.459+04:00   00:00:00:07.499         743 KB         743 KB           0        -
[PCTDynRun]                7    IDLE            04/12/2024 14:08:30.459+04:00   00:00:00:07.499         743 KB         743 KB           0        -
[PCTDynRun]       Active Agent-Sessions: 0 of 2 (0% Busy)
[PCTDynRun]     Utilized Agent-Sessions: 0 of 2 (>801 KB)
[PCTDynRun]        Approx. Agent Memory: 15,392 KB
[PCTDynRun]
[PCTDynRun] Session Manager Metrics (Count-Based)
[PCTDynRun]            # Requests to Session:           0
[PCTDynRun]           # Agent Responses Read:           0 (0 Errors)
[PCTDynRun]         # Agent Requests Written:           0 (0 Errors)
[PCTDynRun]     Concurrent Connected Clients:           0 (Max: 0)
[PCTDynRun]       # Reserve ABLSession Waits:           0
[PCTDynRun]     # Reserve ABLSession Timeout:           0
[PCTDynRun]
[PCTDynRun] Client HTTP Sessions: 0
[PCTDynRun]

BUILD SUCCESSFUL
Total time: 1 second

Server management tasks

The following tasks have a distinct effect on the operation of a PAS instance and should be used with caution and understanding about their intended uses.

Instance operations

  • startup — Uses the tcman utility using either the pasoestart or oeserver command to start the instance.
  • query — Uses the tcman utility using either the pasoestart or oeserver command to query the instance.
  • shutdown — Uses the tcman utility using either the pasoestart or oeserver command to stop the instance.

ABL application operations

  • add — Starts a new MS Agent for an ABL application, provided the maxAgents setting has not yet been reached.
  • stop — Stops a running MS Agent for an ABL application, provided there are any MS Agents to be stopped. It is advised to use the close task to adequately prepare each ABL application for termination which includes terminating any active connections and stopping all running MS Agents.
  • close — Close is a compound task which executes several existing tasks in a specific order to help safely prepare a PAS instance for shutdown. Before and after all of the following tasks are run, the status task is run to get a snapshot of the ABL application. Any deferred log information is then flushed (flush), any available client HTTP sessions are terminated gracefully (trimhttp), and all MS Agents for the ABL application are stopped (stop).
  • reset — Used to either reset internal MS Agent stats or to clear any accumulated deferred log data. In most cases these actions are not needed unless instructed by technical support.
  • trimhttp / trimsingle / trimall / trimidle / refresh — These tasks all affect the termination of sessions which requires additional context for correct operation. Please see the next section for more detail.

Trim sessions

There are two primary types of sessions in use for PAS instances so to avoid confusion the following names are used to distinguish these from each other:

  • Client HTTP session — The session for an HTTP request from a client. Termination of an HTTP client should both cancel the active (in-flight) request as well as terminate that request's runtime context (the ABL session).
  • ABL session — The runtime context in which a request executes ABL code. This is the session of an MS Agent where application code runs (essentially, the AVM).

The term "trim" is a carry-over from Classic AppServer and WebSpeed where agents could be "trimmed" to remove them from their associated broker process. Within the PAS server architecture the same thing can effectively be done, terminating an ABL session from its associated MS Agent. However, be aware of any client (HTTP) connections from the Tomcat web server and gracefully end those connections in addition to terminating the ABL session associated with that HTTP session. This can be determined by viewing the output of the status task.

The following tasks are presented in order of suggested use:

  • trimhttp — For active client requests to a PAS instance it is highly advisable to utilize the trimhttp task when termination is necessary. This task utilizes both the OpenEdge Manager (oemanager.war) and Tomcat Manager (manager.war) webapps to terminate one or more client HTTP sessions as well as its context which is an ABL session. While the primary effect is to terminate the remote connection, this also reduces the total available ABL sessions for the related MS Agent and may require the server to start a new ABL session to handle additional client requests. This utilizes the API endpoint to terminate a single (client HTTP) session.

    This task only works against available HTTP connections. If no active sessions are present, no impact to existing ABL sessions are observed—in this situation one of the three trim tasks in the next section can/should be used.

  • trimsingle / trimall / trimidle — When there are no active or bound/reserved client HTTP sessions, the use of these tasks can be run to reduce the number of running ABL sessions for an MS Agent. This can be an effective means of scaling down an MS Agent which has started a large number of ABL sessions which are no longer of use. All three of these tasks operate in a similar manner, first obtaining a list of current ABL sessions for an MS Agent and iterating over those sessions using any applicable criteria. The trimsingle task only terminates an ABL session which matches the given session ID, while trimidle only terminates an ABL session if its status is reported as IDLE. Before each session is terminated, the current session stack information is written to disk to identify what may have been running at the time the termination was requested. These actions utilize the API endpoint to terminate a single ABL session.
    Note: It is advised to use the trimhttp task first to terminate any active or lingering client HTTP sessions first, then use the appropriate task above to terminate additional ABL sessions.
  • refresh — This task is a built-in operation which behaves like the trimall task with the Finish+Stop termination option. Whereas the trim tasks iterate directly over each ABL session of an MS Agent, refresh acts upon the MS Agent itself. In other words, refresh tells the MS Agent of an ABL application to terminate all of its current ABL sessions, thereby refreshing the MS Agent so that changes to the application can be picked up. The refresh API allows newly created sessions to use the updated persistent procedures, static objects, or online schema changes, and starts running sessions against the new application code. This task is intended to be used for high-availability environments, during a "quiet period" with no user activity, where new code may be deployed but it is not desirable to shut down or restart the entire PAS instance, only to refresh the running MS Agents. See Refresh agents in an ABL application.
    Warning: Do not use the refresh task while the PAS instance is serving active requests or has stuck or busy sessions. refresh unconditionally terminates all ABL sessions in the MS Agent immediately—any in-progress requests could be cut without a graceful drain, which can result in data loss, transaction rollbacks, or corrupted client state. This task is intended for code deployment during a scheduled quiet period when no user activity is expected. Before using refresh, run the trim tasks above to gracefully terminate any active or lingering sessions.

    As an alternative to the suggested trim tasks, the close task gracefully terminates any existing client HTTP sessions, then stops all MS Agents for an ABL application. This allows the MS Agent to return any memory back to the operating system, and then use the add task to start one or more new MS Agents.