OEMANAGER Updates (#33)

* Add more error handling to the CLI/API calls, update usage * Whitespace and comments * Adjusting usage instructions for OEMANAGER --------- Co-authored-by: DustinGrau-PSC <[email protected]>
progress · Mar 14, 2024 · cf3f29e · cf3f29e
1 parent 1861439
commit cf3f29e
Show file tree

Hide file tree

Showing 18 changed files with 251 additions and 63 deletions.
diff --git a/PAS/Management/OEManager/ABL/USAGE.md b/PAS/Management/OEManager/ABL/USAGE.md
@@ -29,12 +29,12 @@ The following represents the default usage for all tasks which can be executed u
      [echo]  Status/Info:
      [echo]
      [echo]  oemanager status - [RO] Obtain MSAgent/connection status information for an ABL App
-     [echo]                     [OPTIONAL] -Dbasemem=819200 - Minimum memory threshold, in bytes, of unused agent sessions
+     [echo]                     [OPTIONAL] -Dbasemem=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]                     [OPTIONAL]    -Dpid=[AGENT_PID]  - Limit stack information to a specific MSAgent process ID
      [echo]                     [OPTIONAL] -Dsessid=[SESSION_ID] - Limit stack information to a specific ABL Session ID
-     [echo]                                                        Requires specifying an MSAgent via pid=[AGENT_PID]
+     [echo]                                                        Requires specifying an MSAgent via -Dpid=[AGENT_PID]
      [echo]
      [echo]  oemanager flush  - [RO] Flush the available deferred log buffer to agent log file
      [echo]
@@ -52,13 +52,9 @@ The following represents the default usage for all tasks which can be executed u
      [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] -Dwebapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active sessions
+     [echo]                      [REQUIRED] -Dwebapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active client sessions
      [echo]                                  The given WebApp is expected to be associated with the provided -Dablapp name
-     [echo]                      [OPTIONAL] -Dsleep=1 - Sleep time in minutes after stop
-     [echo]
-     [echo]  oemanager refresh - Refresh ABL Sessions for each MSAgent for an ABL App (OE 12 Only)
-     [echo]                      Note: This will essentially terminate all sessions (gracefully),
-     [echo]                            and prepare the Agent to pick up any R-code changes
+     [echo]                      [OPTIONAL] -Dsleep=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] -Dresettype=stats [stats|logs]
@@ -80,7 +76,7 @@ The following represents the default usage for all tasks which can be executed u
      [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]                         [OPTIONAL] -Dterminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish/stop
+     [echo]                         [OPTIONAL] -Dterminateopt=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
@@ -93,6 +89,11 @@ The following represents the default usage for all tasks which can be executed u
      [echo]                         [OPTIONAL]       -Dsessid=[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] -Dterminateopt=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.
 
 ## Tailoring ##
 
@@ -131,7 +132,7 @@ The following have a distinct effect on the operation of a PAS instance and shou
 
 - **add** - [Starts a new MSAgent](https://docs.progress.com/bundle/pas-for-openedge-reference/page/Add-a-multi-session-agent.html) for an ABL Application, provided the maxAgents setting has not yet been reached.
 - **stop** - [Stops a running MSAgent](https://docs.progress.com/bundle/pas-for-openedge-reference/page/Stop-a-multi-session-agent.html) for an ABL Application, provided there are any MSAgents 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 MSAgents.
-- **close** - This is a synthetic task which executes many of the 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 MSAgents for the ABL Application are stopped (stop).
+- **close** - This 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 MSAgents for the ABL Application are stopped (stop).
 - **reset** - Used to either reset internal MSAgent stats or to [clear any accumulated deferred log data](https://docs.progress.com/bundle/pas-for-openedge-reference/page/Reset-deferred-log-buffer.html). In most cases these actions will not be needed unless instructed by tech 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 on **Trimming Sessions** for those details.
 
@@ -148,6 +149,6 @@ We use the term "trim" as a carry-over from Classic AppServer and WebSpeed where
 	- This task will only work against available HTTP connections. If no active sessions are present, no impact to existing ABL Sessions will be observed--in this situation one of the 3 "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 may be run to reduce the number of running ABL Sessions for an MSAgent. This can be an effective means of scaling down an MSAgent which has started a large number of ABL Sessions which are no longer of use. All 3 of these tasks operate in a similar manner, first obtaining a list of current ABL Sessions for an MSAgent and iterating over those sessions using any applicable criteria. For the "trimsingle" this will only terminate an ABL Session which matches the given session ID, while "trimidle" will only terminate an ABL Session if its status is reported as "IDLE". Before each session is terminated, the current session stack information will be 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](https://docs.progress.com/bundle/pas-for-openedge-reference/page/Terminate-an-ABL-session.html) (note: link goes to the OEJMX query as we do not have a page which covers this action via the OEM REST API's).
 	- 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 similar to the "trimall" task with one crucial difference: Whereas the "trim" tasks (just covered above) will iterate directly over each ABL Session of an MSAgent, this acts upon the MSAgent itself. In other words, refresh tells the MSAgent of an ABL Application to terminate all of its current ABL Sessions, thereby refreshing the MSAgent 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 was 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 MSAgents. More information on this operation may be found [here in the product documentation](https://docs.progress.com/bundle/pas-for-openedge-management/page/Refresh-agents-in-an-ABL-application.html).
+- **refresh** - This task is a built-in operation which behaves similar to the "trimall" task with the Finish+Stop termination option. Whereas the "trim" tasks (just covered above) will iterate directly over each ABL Session of an MSAgent, this acts upon the MSAgent itself. In other words, refresh tells the MSAgent of an ABL Application to terminate all of its current ABL Sessions, thereby refreshing the MSAgent 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 was 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 MSAgents. More information on this operation may be found [here in the product documentation](https://docs.progress.com/bundle/pas-for-openedge-management/page/Refresh-agents-in-an-ABL-application.html).
 	- **Warning:** This task is not intended to be used when a PAS instance is serving active requests, or if it may have stuck/busy sessions. You should make use of the "trim" tasks above to gracefully terminate those sessions prior to using the refresh task.
 	- As an alternative to the suggested "trim" tasks, the "**close**" task will gracefully terminate any existing Client HTTP Sessions then stop all MSAgents for an ABL Application. This allows the MSAgent to return any memory back to the OS, and then use the "**add**" task to start one or more new MSAgents.
diff --git a/PAS/Management/OEManager/ABL/conf/oemanager.xml b/PAS/Management/OEManager/ABL/conf/oemanager.xml
@@ -59,18 +59,6 @@
         <echo message="                     [REQUIRED] -Dwebapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active client sessions"/>
         <echo message="                                 The given WebApp is expected to be associated with the provided -Dablapp name"/>
         <echo message="                     [OPTIONAL] -Dsleep=${sleep} - Sleep time in minutes after stop, prior to final 'status' output"/>
-        <if>
-            <equals arg1="${oeMajor}" arg2="11"/>
-            <then>
-                <!-- No additional options for OpenEdge 11. -->
-            </then>
-            <else>
-                <!-- Additional options available for OpenEdge 12 and later. -->
-                <echo message="${line.separator} ${util.name} refresh - Refresh ABL Sessions for each MSAgent for an ABL App"/>
-                <echo message="                     Note: This will essentially terminate all sessions (gracefully),"/>
-                <echo message="                           and prepare the Agent to pick up any R-code changes"/>
-            </else>
-        </if>
         <echo message="${line.separator} ${util.name} reset   - Reset an aspect of each MSAgent for an ABL App"/>
         <echo message="                     [REQUIRED] -Dresettype=${resettype} [stats|logs]"/>
         <echo message="${line.separator} ${util.name} stop    - Gracefully stop one or all MSAgents (+stacks output) for an ABL App"/>
@@ -86,7 +74,7 @@
         <echo message="                        [OPTIONAL] -Dterminateopt=${terminateopt} - Termination Option: 0=graceful, 1=forced, 2=finish+stop"/>
         <echo message="${line.separator} ${util.name} trimall    - Trim all available ABL Sessions (via the Agent Manager) for each MSAgent for an ABL App"/>
         <echo message="                        Note: For any busy sessions considered stuck use 'trimhttp' with a specific Session ID"/>
-        <echo message="                        [OPTIONAL] -Dterminateopt=${terminateopt} - Termination Option: 0=graceful, 1=forced, 2=finish/stop"/>
+        <echo message="                        [OPTIONAL] -Dterminateopt=${terminateopt} - Termination Option: 0=graceful, 1=forced, 2=finish+stop"/>
         <echo message="${line.separator} ${util.name} trimidle   - Trim only the IDLE ABL Sessions (via the Agent Manager) for each MSAgent for an ABL App"/>
         <echo message="                        Allows for manually scaling down an MSAgent which may have many unused ABL Sessions"/>
         <echo message="                        [OPTIONAL] -Dterminateopt=${terminateopt} - Termination Option: 0=graceful, 1=forced, 2=finish+stop"/>
@@ -97,6 +85,19 @@
         <echo message="                        [OPTIONAL]       -Dsessid=[SESSION_ID]  - Alphanumeric Client Session ID to be stopped"/>
         <echo message="                                          When no session ID provided, all available Client HTTP Sessions will be expired"/>
         <echo message="                        [OPTIONAL] -Dterminateopt=${terminateopt} - Termination Option: 0=graceful, 1=forced, 2=finish+stop"/>
+        <if>
+            <equals arg1="${oeMajor}" arg2="11"/>
+            <then>
+                <!-- No additional options for OpenEdge 11. -->
+            </then>
+            <else>
+                <!-- Additional options available for OpenEdge 12 and later. -->
+                <echo message="${line.separator} ${util.name} refresh    - Refresh ABL Sessions for each MSAgent for an ABL App"/>
+                <echo message="                        Note: This will terminate all sessions using the 'finish+stop' option,"/>
+                <echo message="                              which prepares the MSAgent to pick up available R-code changes."/>
+                <echo message="                              Use this only during a 'quiet period' for your application."/>
+            </else>
+        </if>
         <echo message="${line.separator}"/>
         <echo message="${line.separator}Current parameter values, override via command line or 'oemanager.properties':"/>
         <echo message="    -Dscheme=${scheme}"/>

diff --git a/PAS/Management/OEManager/ABL/release.txt b/PAS/Management/OEManager/ABL/release.txt
@@ -1 +1 @@
-2024-03-07T10:53:42.096
+2024-03-12T14:42:02.106
diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/addAgent.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/addAgent.p
@@ -1,5 +1,5 @@
 /*
-    Copyright 2020-2023 Progress Software Corporation
+    Copyright 2020-2024 Progress Software Corporation
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -68,6 +68,9 @@ oMgrConn:LogCommand("RUN", this-procedure:name).
 message substitute("Starting new MSAgent for &1...", cAblApp).
 message oMgrConn:AddAgent(cAblApp).
 
+catch err as Progress.Lang.Error:
+    put unformatted substitute("~nError while communicating with PASOE instance: &1", err:GetMessage(1)) skip.
+end catch.
 finally:
     /* Return value expected by PCT Ant task. */
     {&_proparse_ prolint-nowarn(returnfinally)}

diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/flushLogs.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/flushLogs.p
@@ -1,5 +1,5 @@
 /*
-    Copyright 2020-2023 Progress Software Corporation
+    Copyright 2020-2024 Progress Software Corporation
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -74,7 +74,8 @@ oMgrConn:LogCommand("RUN", this-procedure:name).
 
 /* Initial URL to obtain a list of all MSAgents for an ABL Application. */
 message substitute("Flushing deferred log buffer for MSAgents of &1...", cAblApp).
-oAgents = oMgrConn:GetAgents(cAblApp).
+assign oAgents = oMgrConn:GetAgents(cAblApp).
+
 if oAgents:Length eq 0 then
     message "No MSAgents running".
 else
@@ -96,7 +97,11 @@ on stop undo, next AGENTBLK:
         message substitute("Agent PID &1 not AVAILABLE, skipping flush.", oAgent:GetCharacter("pid")).
 end. /* iLoop - agent */
 
+catch err as Progress.Lang.Error:
+    put unformatted substitute("~nError while communicating with PASOE instance: &1", err:GetMessage(1)) skip.
+end catch.
 finally:
     /* Return value expected by PCT Ant task. */
+    {&_proparse_ prolint-nowarn(returnfinally)}
     return string(0).
 end finally.
diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLockStats.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLockStats.p
@@ -88,9 +88,9 @@ repeat:
 
     // As of OE 12.5 a new field _Connect-Details was added to hold a unique string to identify connections from a PAS instance.
     // https://docs.progress.com/bundle/openedge-whats-new/page/Whats-New-in-OpenEdge-12.5.html#ariaid-title15
-	assign hConnDetFld = hConnBuffer:buffer-field("_Connect-Details") no-error. // Purposeful no-error here.
-	if error-status:error then
-		error-status:error = false. // Ignore any generated error from above.
+    assign hConnDetFld = hConnBuffer:buffer-field("_Connect-Details") no-error. // Purposeful no-error here.
+    if error-status:error then
+        error-status:error = false. // Ignore any generated error from above.
     if valid-object(hConnDetFld) then do:
         // The format of the data in this field should be "Container:Host:AgentPID:SessID"
         assign cConnDetail = hConnDetFld:buffer-value().

diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p
@@ -1,5 +1,5 @@
 /*
-    Copyright 2020-2023 Progress Software Corporation
+    Copyright 2020-2024 Progress Software Corporation
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -266,6 +266,10 @@ procedure getAblApplications:
         if oApp:Has("name") and oApp:Has("type") and oApp:GetCharacter("type") eq "OPENEDGE" then
             oAblApps:Add(new OpenEdge.Core.String(oApp:GetCharacter("name"))).
     end. /* iLoop - Application */
+
+    catch err as Progress.Lang.Error:
+        put unformatted substitute("~nUnable to get application list from PASOE instance: &1", err:GetMessage(1)) skip.
+    end catch.
 end procedure.
 
 procedure getAblAppAgents:

diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStacks.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStacks.p
@@ -143,6 +143,9 @@ else do:
     end. /* iLoop - agent */
 end. // All Agents
 
+catch err as Progress.Lang.Error:
+    put unformatted substitute("~nError while communicating with PASOE instance: &1", err:GetMessage(1)) skip.
+end catch.
 finally:
     /* Return value expected by PCT Ant task. */
     {&_proparse_ prolint-nowarn(returnfinally)}

diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStatus.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStatus.p
@@ -1,5 +1,5 @@
 /*
-    Copyright 2020-2023 Progress Software Corporation
+    Copyright 2020-2024 Progress Software Corporation
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -279,6 +279,10 @@ procedure GetApplications:
     assign lIsMin122 = (oVersion:Major eq 12 and oVersion:Minor ge 2) or oVersion:Major gt 12.
     assign lIsMin127 = (oVersion:Major eq 12 and oVersion:Minor ge 7) or oVersion:Major gt 12.
     assign lIsMin128 = (oVersion:Major eq 12 and oVersion:Minor ge 8) or oVersion:Major gt 12.
+
+    catch err as Progress.Lang.Error:
+        put unformatted substitute("~nUnable to get application list from PASOE instance: &1", err:GetMessage(1)) skip.
+    end catch.
 end procedure.
 
 /* Get the configured max for ABLSessions/Connections per MSAgent, along with min/max/initial MSAgents. */