diff --git a/PAS/Management/OEManager/ABL/README.md b/PAS/Management/OEManager/ABL/README.md index 32796e4..a10a3a1 100644 --- a/PAS/Management/OEManager/ABL/README.md +++ b/PAS/Management/OEManager/ABL/README.md @@ -1,128 +1,41 @@ -# ABL Management # +# OEManager CLI Tools # -Utilizing the [RESTful API's](https://docs.progress.com/bundle/pas-for-openedge-reference/page/REST-API-Reference-for-oemanager.war.html) offered by the oemanager WebApp, the included ABL code may provide either a comprehensive view of a running instance or means to manage an ABL Application. All actions can be run via a command-line interface using ANT tasks on either Windows or Unix environments. +*Formerly referred to as the "PROANT Tools"* -## Requirements ## +This suite of tools utilizes the [RESTful API's](https://docs.progress.com/bundle/pas-for-openedge-reference/page/REST-API-Reference-for-oemanager.war.html) offered by the **oemanager** WebApp to provide a comprehensive insight to a running PAS instance or to manage any ABL Application belonging to a PAS instance. All operations are executed via a command-line interface (using ANT and PCT internally) on either Windows or Linux environments. -Use of **proant** is required to execute the **build.xml** included. This can be accessed via the `DLC/bin` directory, typically via a **PROENV** session. If necessary, ABL code may be compiled before deployment in an environment where a 4GL compiler is not available. +## Requirements ## -**Note:** Some data may only be displayed in an OpenEdge 12 environment, such as the Dynamic Session Limit which was added as part of the Agent self-management feature. Other values such as **RequestID** (where applicable) will only be displayed if the **Enhanced MDC Logging** is enabled--this is on by default in OpenEdge 12 though it must be manually enabled in OpenEdge 11.7.x (via **openedge_setenv.[bat|sh]**). And lastly, some runtime metrics such as counts and time values will only be present if **collectMetrics** has been set to 3 for the AppServer and each WebApp (via openedge.properties). +1. Run a **PROENV** session which will set the necessary environment variables to execute the tools. This will provide access to the DLC and JAVA_HOME environment variables and any OpenEdge binaries such as "PROANT" which is useful for deployment. + - You should ideally the latest OpenEdge release version available to you, or at a minimum the same release version as used by the PAS for OpenEdge instances you wish to manage. +1. The OpenEdge Manager (oemanager.war) and Tomcat Manager (manager.war) webapps must be deployed to the PAS instance in order to make use of these tools. For ease of deployment, run the `proant deploy_oemanager` or `proant deploy_manager` as necessary to install the webapps into a PAS instance specified via the parameter `-Dinstance=[PATH_TO_INSTANCE]`. + - **WARNING:** It is strongly recommended to [secure the oemanager and manager WebApps](https://docs.progress.com/bundle/openedge-security-and-auditing/page/Secure-the-Tomcat-Manager-and-OpenEdge-Manager-web-applications.html) when deployed in a production environment. You will need to update the `oemanager.properties` after deployment with any updated credentials. ## Deployment ## -Simply run **proant** from this directory to obtain usage information as shown below. Parameters may be specified via command-line or by editing the `build.properties` file in advance. For actions which will alter a running PAS instance (read: those without the RO indicator), individual OEM-API commands will be logged to a `commands.log` file. - - [echo] Usage Instructions: - [echo] - [echo] TCMAN Shortcuts: - [echo] - [echo] proant query - Use TCMAN to query the oepas1 PAS instance - [echo] - [echo] proant startup - Use TCMAN to start the oepas1 PAS instance - [echo] [OPTIONAL] -Dtimeout=300 - Time to wait for a proper startup - [echo] - [echo] proant shutdown - Use TCMAN to stop the oepas1 PAS instance - [echo] [OPTIONAL] -Dtimeout=300 - Time to wait for a proper shutdown - [echo] - [echo] - [echo] Internal Tools: - [echo] - [echo] proant inventory - Bundle useful PAS instance files (as .zip) for support tickets - [echo] - [echo] proant compile - Compile all utility procedures to r-code (for production use) - [echo] - [echo] - [echo] Status/Info: - [echo] - [echo] proant 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] - [echo] proant stacks - [RO] Obtain stack information for all MSAgents for an ABL App - [echo] - [echo] proant flush - [RO] Flush the available deferred log buffer to agent log file - [echo] - [echo] proant 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] [OPTIONAL] -Dcodepage=UTF-8 - Codepage - [echo] [OPTIONAL] -Dcollation=BASIC - Collation - [echo] [OPTIONAL] -Ddb.name=Sports2020 - Database name to check - [echo] [OPTIONAL] -Ddb.host=localhost - Database host to check - [echo] [OPTIONAL] -Ddb.port=8600 - Database port to check - [echo] - [echo] proant users - [RO] Alias for 'locks' task - [echo] - [echo] - [echo] Agent Management: - [echo] - [echo] proant add - Add (read: start) one new MSAgent for an ABL App - [echo] - [echo] proant 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 for Tomcat Manager to terminate active 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] proant clean - Alias for 'close' task [Deprecated] - [echo] - [echo] proant 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] - [echo] proant reset - Reset an aspect of each MSAgent for an ABL App - [echo] [REQUIRED] -Dresettype=stats [stats|logs] - [echo] - [echo] proant stop - Gracefully stop one or all MSAgents (+stacks output) for an ABL App - [echo] [OPTIONAL] -Dwaitfinish=120000 - How long to wait in milliseconds if the MSAgent is busy serving a request - [echo] [OPTIONAL] -Dwaitafter=60000 - Additional time to wait in milliseconds before killing [hard stop] the MSAgent - [echo] [OPTIONAL] -Dpid=[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] proant trimsingle - Trim a single ABL Session (via the Agent Manager) for a specific MSAgent - [echo] [REQUIRED] -Dpid=[AGENT_PID] - Numeric process ID of the MSAgent for context - [echo] [REQUIRED] -Dsessid=[SESSION_ID] - Numeric ID for the ABL Session to be stopped - [echo] [OPTIONAL] -Dterminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop - [echo] - [echo] proant 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] - [echo] proant 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] [OPTIONAL] -Dterminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop - [echo] - [echo] proant 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] -Dwebapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active sessions - [echo] The given WebApp is expected to be associated with the provided -Dablapp name - [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] - [echo] Available common parameters with their defaults, override as necessary: - [echo] -Dscheme=http - [echo] -Dhost=localhost - [echo] -Dport=8810 - [echo] -Duserid=tomcat - [echo] -Dpasswd=tomcat - [echo] -Dpas.root=C:\OpenEdge\WRK - PAS parent directory - [echo] -Dinstance=oepas1 - Physical instance name - [echo] -Dablapp=oepas1 - ABL Application name - [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\oepas1 +The deployment method has changed since previous versions with use of a new **utils.zip** file now being preferred. The tools may be deployed either automatically or manually via the following processes: -## Output ## +**Automated Deployment** + +Run the command `proant deploy -Dpath=[PATH_TO_INSTANCE]` to expand/unzip the **utils.zip** into your PAS instance's **CATALINA_BASE/utils/** folder. A new folder will be created if necessary, and any existing files will be overwritten if deploying on top of a prior deployment. This will overwrite any customization to an `oemanager.properties` file. + +**Manual Deployment** -Output for all commands should be displayed via standard out and appear within the same terminal/command window where executed. There are some log files generated for sanity checks as part of the normal operation. All commands will be logged to a `commands.log` file and cannot be disabled as this ensures an audit trail of management actions taken for a PAS instance. The included `logging.config` enabled logging via the ABL Logger framework for additional insight into the operations made against a PAS instance and can be configured with varying logging levels and output. By default the logging level is set to DEBUG and will output messages to a `OEMgrConn.log` file. This will produce output similar to the `commands.log` file though it can be made more silent by changing the logging level to ERROR or lower. +Unzip the **utils.zip** file into a new "utils" folder on the target OS image (physical or virtual machine, or container). This may be placed in either a PAS instance you have direct access to (via the OS filesystem) or a central location if desiring to manage multiple remote PAS instances. + +- If placed within a PAS instance in a "utils" folder the tools will automatically tailor themselves to use properties from the PAS instance, such as the HTTP or HTTPS port. +- If **not** placed directly within a PAS instance then you must either pass command-line parameters or edit the `oemanager.properties` file to supply the necessary defaults for either or both of the following groups of properties: + - To control remote PAS instances: set the `scheme`, `hostname`, and `port` properties for the intended instance. + - eg. "-Dscheme=http -Dhostname=localhost -Dport=8810" + - To control local PAS instances: the `pas.root` and `instance` properties (these will form the CATALINA_BASE path). + - eg. "-Dpas.root=C:/OpenEdge/WRK -Dinstance=oepas1" for an instance at C:/OpenEdge/WRK/oepas1 + +## Usage ## + +# For a full explanation of available tasks and use-cases please see the [expanded usage guide in USAGE.md](USAGE.md). # + +## Output ## -## Security Notes ## +Output for all commands should be displayed via standard out and appear within the same terminal/command window where executed. Log files may be generated for sanity checks as part of the normal operation. All commands will be logged to a `commands.log` file and cannot be disabled as this ensures an audit trail of management actions taken for a PAS instance. The included `logging.config` enables logging via the ABL Logger framework for additional insight into the operations made against a PAS instance and can be configured with alternate logging levels and output options. By default, the logging level is set to DEBUG and will output messages to a `OEMgrConn.log` file. This will produce output similar to the `commands.log` file though it can be silenced by changing the logging level to ERROR or lower. -It is strongly recommended to [secure the oemanager and manager WebApps](https://docs.progress.com/bundle/openedge-security-and-auditing/page/Secure-the-Tomcat-Manager-and-OpenEdge-Manager-web-applications.html) when deployed in a production environment. \ No newline at end of file +**Note:** Some data may only be displayed in an OpenEdge 12 environment, such as the Dynamic Session Limit which was added as part of the Agent self-management feature. Other values such as **RequestID** (where applicable) will only be displayed if the **Enhanced MDC Logging** is enabled--this is enabled by default in OpenEdge 12 releases though it must be manually enabled in OpenEdge 11.7.x (via **openedge_setenv.[bat|sh]**). Lastly, some runtime metrics such as counts and time values will only be present if **collectMetrics** has been set to 3 for the AppServer and each WebApp (via openedge.properties). \ No newline at end of file diff --git a/PAS/Management/OEManager/ABL/USAGE.md b/PAS/Management/OEManager/ABL/USAGE.md new file mode 100644 index 0000000..f9afafc --- /dev/null +++ b/PAS/Management/OEManager/ABL/USAGE.md @@ -0,0 +1,141 @@ +# OEManager CLI Tools - Usage Guide # + +Execute the `oemanager[.bat]` command from within the utils folder to run the desired tasks from the command line. Where possible, default values will be determined automatically for HTTP/S ports, server paths, the instance's name, and the default ABL Application name. Any required or optional parameters may be overridden via the command line or by editing the `oemanager.properties` file in advance. + +Note that each request to an OEM-API endpoint will be automatically logged to a `commands.log` file. No sensitive data will be included in these logged messages, only PID's and operationally-relevant information will be included in the URL or as query parameters to the API endpoint. + +## Basic Usage ## + +The following represents the default usage for all tasks which can be executed using the CLI tools and is the standard output when the `oemanager[.bat]` command is run without a task name. + + [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] -Dtimeout=300 - Time (seconds) to wait for a proper startup + [echo] + [echo] oemanager shutdown - Use TCMAN to stop the PAS instance + [echo] [OPTIONAL] -Dtimeout=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] [OPTIONAL] -Dbasemem=819200 - Minimum memory threshold, in bytes, of unused agent sessions + [echo] + [echo] oemanager stacks - [RO] Obtain stack information for all MSAgents for an ABL App + [echo] + [echo] oemanager flush - [RO] Flush the available deferred log buffer to agent log file + [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] -Dpf=[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] + [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] 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 clean - Alias for 'close' task [Deprecated] + [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] + [echo] oemanager reset - Reset an aspect of each MSAgent for an ABL App + [echo] [REQUIRED] -Dresettype=stats [stats|logs] + [echo] + [echo] oemanager stop - Gracefully stop one or all MSAgents (+stacks output) for an ABL App + [echo] [OPTIONAL] -Dwaitfinish=120000 - How long to wait (milliseconds) if the MSAgent is busy serving a request + [echo] [OPTIONAL] -Dwaitafter=60000 - Additional time to wait (milliseconds) before killing [hard stop] the MSAgent + [echo] [OPTIONAL] -Dpid=[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] -Dpid=[AGENT_PID] - Numeric process ID of the MSAgent for context + [echo] [REQUIRED] -Dsessid=[SESSION_ID] - Numeric ID for the ABL Session to be stopped + [echo] [OPTIONAL] -Dterminateopt=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] [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 + [echo] [OPTIONAL] -Dterminateopt=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] -Dwebapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active sessions + [echo] The given WebApp is expected to be associated with the provided -Dablapp name + [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 + +## Use-Cases ## + +The following should cover specific cases of when and how to use the tasks listed above in the usage instructions. + +### Obtaining Runtime Data ### + +The following tasks are read-only and simply report data from a running PAS instance. + +- **status** - This will be 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) this shows the current state of all MSAgents and their ABL Sessions, and HTTP Connections to the PAS instance. +- **locks / users** - This uses one or more connected databases (specified via a .pf file) to correlate any table locks to ABL code running in the application. This utilizes information about current requests to an MSAgent, 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, this forces any current data in the deferred log buffer (up to the configured number of lines) to be flushed to the named log file. Please [see this following documentation](https://docs.progress.com/bundle/pas-for-openedge-management/page/Use-deferred-logging-in-PAS-for-OpenEdge.html) 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 MSAgent. This data will only be visible for MSAgents which are currently busy executing ABL code. Note that all tasks which terminate sessions or MSAgents will automatically generate this same stack information. + +### Server Management Tasks ### + +The following 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 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). +- **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. + +### Trimming Sessions ### + +There are two primary types of "sessions" in use for PAS instances so to avoid confusion we will be using the following names 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 MSAgent where application code runs (essentially, the AVM). + +We use the term "trim" as 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 we can effectively do the same thing, terminating an ABL Session from its associated MSAgent. However, we must 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. + +- **trimhttp** - For active client requests to a PAS instance it is highly advisable to utilize the "trimhttp" task when termination is necessary. This will utilize 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. So while the primary effect is to terminate the remote connection this will also reduce the total available ABL Sessions for the related MSAgent 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](https://docs.progress.com/bundle/pas-for-openedge-reference/page/Terminate-a-session.html). + - This task will only work against available HTTP connections. If no active sessions are present, no impact to existing ABL Sessions will be observed. +- **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 is meant to be used for high-availability, 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). + - As an alternative to this action, 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/bin/oemanager b/PAS/Management/OEManager/ABL/bin/oemanager new file mode 100644 index 0000000..519194f --- /dev/null +++ b/PAS/Management/OEManager/ABL/bin/oemanager @@ -0,0 +1,53 @@ +#!/bin/sh +# OpenEdge - OEManager CLI Utility +PROG=`basename $0` + +# Utility must be run with DLC environment variable set +if [ ! -d $DLC/ant ] +then + echo "Progress DLC environment variable may not be set correctly." + echo "Set DLC variable to Progress installation directory." + echo + exit 1 +fi + +# Set the java environment via java_env; requires DLC +if [ ! -f $DLC/bin/java_env ] +then + echo "Progress $PROG Messages:" + echo + echo "java_env could not be found." + echo + echo "JAVA environment not set correctly." + echo "Progress DLC environment variable may not be set correctly." + echo "Set DLC variable to Progress installation directory." + echo + echo "Progress DLC setting: $DLC" + echo + exit 1 +fi + +# Set the JAVA environment +. $DLC/bin/java_env + +# Build the Apache Ant execution script path +ANTSCRIPT=${ANTSCRIPT-$DLC/ant/bin/ant} + +if [ ! -f $ANTSCRIPT ] +then + echo "Progress $PROG Messages:" + echo + echo "The OpenEdge Apache Ant launch script could not be found." + echo + echo "Progress DLC environment variable may not be set correctly." + echo "Set DLC variable to Progress installation directory." + echo + echo "Progress DLC setting: $DLC" + echo "Script not found: $ANTSCRIPT" + echo + exit 1 +fi + +# use the oemanager.xml as task instructions to Ant, passing all other parameters +ANT_HOME=$DLC/ant ; export ANT_HOME +exec $ANTSCRIPT -f oemanager.xml $@ diff --git a/PAS/Management/OEManager/ABL/bin/oemanager.bat b/PAS/Management/OEManager/ABL/bin/oemanager.bat new file mode 100644 index 0000000..70980df --- /dev/null +++ b/PAS/Management/OEManager/ABL/bin/oemanager.bat @@ -0,0 +1,45 @@ +@echo off +REM OpenEdge - OEManager CLI Utility + +REM Utility must be run with DLC environment variable set +if exist "%DLC%"\ant goto BIN + echo. + echo Progress DLC environment variable may not be set correctly. + echo Set DLC variable to Progress installation directory. + echo. + pause + goto END + +:BIN +if "%ANTSCRIPT%"=="" set ANTSCRIPT="%DLC%"\ant\bin\ant.bat +if exist "%ANTSCRIPT%" goto START + cls + echo AppServer %0 Messages: + echo. + echo The OpenEdge Apache Ant launch script could not be found. + echo. + echo Progress DLC environment variable may not be set correctly. + echo Set DLC variable to Progress installation directory. + echo. + echo Progress DLC setting: %DLC% + echo Script not found: %ANTSCRIPT% + echo. + pause + goto END + +:START +REM Remember the original ANT_HOME +set _ANT_HOME=%ANT_HOME% +set ANT_HOME="%DLC%"\ant + +REM Set JAVA_HOME by calling java_env +if exist "%DLC%\bin\java_env.bat" ( + call "%DLC%\bin\java_env.bat" +) + +REM Use the oemanager.xml as task instructions to Ant, passing all other parameters +call "%ANTSCRIPT%" -f oemanager.xml %* +set ANT_HOME=%_ANT_HOME% +goto END + +:END diff --git a/PAS/Management/OEManager/ABL/build.properties b/PAS/Management/OEManager/ABL/build.properties deleted file mode 100644 index ff3492b..0000000 --- a/PAS/Management/OEManager/ABL/build.properties +++ /dev/null @@ -1,26 +0,0 @@ -# build.properties file -# -#scheme=http -#host=localhost -#port=8810 -#userid=tomcat -#passwd=tomcat -#ablapp=oepas1 -#webapp= -# -#basemem=819200 -#terminateopt=0 -#timeout=300 -#waitfinish=120000 -#waitafter=60000 -# -#pas.root= -#instance=oepas1 -# -sleep=1 -# -#codepage=UTF-8 -#collation=BASIC -#db.name=Sports2020 -#db.host=localhost -#db.port=8600 \ No newline at end of file diff --git a/PAS/Management/OEManager/ABL/build.xml b/PAS/Management/OEManager/ABL/build.xml index 3dbaddc..0882a41 100644 --- a/PAS/Management/OEManager/ABL/build.xml +++ b/PAS/Management/OEManager/ABL/build.xml @@ -1,7 +1,7 @@ - + - - - - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + @@ -159,34 +87,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -232,68 +132,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -332,9 +170,10 @@ + - + @@ -344,48 +183,10 @@ - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -393,19 +194,19 @@ - + - - + + - + @@ -415,403 +216,98 @@ - + - - + + + - - - - - + + + + + + + - - - - - - - - - - ${pas.path}${line.separator} - - - ${prop.dir.contents} - - - - - - - - - - - - - - - - - - - - - - - - - - + + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + - - - - - - - - - - - - - - + - - + + + + + - - - - - - - - - - - - - + + - + - - - - - - - - - - - - - - - - - + + + + + + + + + + - - - + - - + + + + + - - - - - - - - - - - - - - - + + diff --git a/PAS/Management/OEManager/ABL/logging.config b/PAS/Management/OEManager/ABL/conf/logging.config similarity index 100% rename from PAS/Management/OEManager/ABL/logging.config rename to PAS/Management/OEManager/ABL/conf/logging.config diff --git a/PAS/Management/OEManager/ABL/conf/oemanager.properties b/PAS/Management/OEManager/ABL/conf/oemanager.properties new file mode 100644 index 0000000..ed0c0a4 --- /dev/null +++ b/PAS/Management/OEManager/ABL/conf/oemanager.properties @@ -0,0 +1,46 @@ +# build.properties file - Modify as Needed +# +# Changing the scheme will affect the port +# used when run from within a PAS instance +# +#scheme=[http|https] +# +# By default localhost is assumed for local +# PAS instances, though both the host and port +# may be set to manage a remote PAS instance +# +#host=localhost +#port= +# +# These are best set via the command line +# parameters unless these are static values +# for the intended PAS instance +# +#ablapp= +#webapp= +# +# Modify to match your credentials +# when secured for production use! +# +#userid=tomcat +#passwd=tomcat +# +# Override when not executing the tasks +# from within a PAS instance in /utils, +# though you wish to manage a local PAS +# instance on the local filesystem +# +#pas.root=path_to_parent_directory +#instance=folder_name_of_instance +# +# +# Override these only when necessary: +# +#basemem=819200 +#terminateopt=0 +#timeout=300 +#waitfinish=120000 +#waitafter=60000 +# +# Sleep time for "close" task +sleep=1 \ No newline at end of file diff --git a/PAS/Management/OEManager/ABL/conf/oemanager.xml b/PAS/Management/OEManager/ABL/conf/oemanager.xml new file mode 100644 index 0000000..bcd8c83 --- /dev/null +++ b/PAS/Management/OEManager/ABL/conf/oemanager.xml @@ -0,0 +1,1025 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ${catalina.base}${line.separator} + + + ${prop.dir.contents} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/PAS/Management/OEManager/ABL/conf/sample.pf b/PAS/Management/OEManager/ABL/conf/sample.pf new file mode 100644 index 0000000..347da11 --- /dev/null +++ b/PAS/Management/OEManager/ABL/conf/sample.pf @@ -0,0 +1,5 @@ +-cpinternal UTF-8 +-cpstream UTF-8 +-cpcase BASIC +-cpcoll BASIC +-db Sports2020 -H localhost -S 8600 -ro -cpinternal UTF-8 -cpcoll BASIC \ No newline at end of file diff --git a/PAS/Management/OEManager/ABL/release.txt b/PAS/Management/OEManager/ABL/release.txt index ed6a386..0d64597 100644 --- a/PAS/Management/OEManager/ABL/release.txt +++ b/PAS/Management/OEManager/ABL/release.txt @@ -1 +1 @@ -2023-01-19T15:27:31.243 \ No newline at end of file +2023-03-06T08:34:22.917 \ No newline at end of file diff --git a/PAS/Management/OEManager/ABL/addAgent.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/addAgent.p similarity index 100% rename from PAS/Management/OEManager/ABL/addAgent.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/addAgent.p diff --git a/PAS/Management/OEManager/ABL/flushLogs.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/flushLogs.p similarity index 100% rename from PAS/Management/OEManager/ABL/flushLogs.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/flushLogs.p diff --git a/PAS/Management/OEManager/ABL/getLockStats.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLockStats.p similarity index 100% rename from PAS/Management/OEManager/ABL/getLockStats.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLockStats.p diff --git a/PAS/Management/OEManager/ABL/getLocks.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p similarity index 99% rename from PAS/Management/OEManager/ABL/getLocks.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p index 97292a4..79b52be 100644 --- a/PAS/Management/OEManager/ABL/getLocks.p +++ b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p @@ -121,7 +121,7 @@ do iLoop = 1 to num-dbs: /* Scan all locks for this DB */ message substitute("~tGetting lock stats for &1...", cDB). - run getLockStats.p (input-output table ttLock by-reference). + run OpenEdge/ApplicationServer/Cli/getLockStats.p (input-output table ttLock by-reference). end. /* Display table lock information to screen. */ diff --git a/PAS/Management/OEManager/ABL/getStacks.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStacks.p similarity index 100% rename from PAS/Management/OEManager/ABL/getStacks.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStacks.p diff --git a/PAS/Management/OEManager/ABL/getStatus.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStatus.p similarity index 99% rename from PAS/Management/OEManager/ABL/getStatus.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStatus.p index 71d2093..fd600da 100644 --- a/PAS/Management/OEManager/ABL/getStatus.p +++ b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getStatus.p @@ -546,7 +546,7 @@ procedure GetAgents: end. /* for each ttAgentSession */ /* Output summary information about agent-sessions, such as how many are busy out of the total count. */ - put unformatted substitute("~t active Agent-Sessions: &1 of &2 (&3% Busy)", + put unformatted substitute("~t Active Agent-Sessions: &1 of &2 (&3% Busy)", iBusySess, iTotSess, if iTotSess gt 0 then round((iBusySess / iTotSess) * 100, 1) else 0) skip. /* Establish an educated guess on how many sessions have been utilized via a baseline memory value. */ diff --git a/PAS/Management/OEManager/ABL/refreshAgents.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/refreshAgents.p similarity index 100% rename from PAS/Management/OEManager/ABL/refreshAgents.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/refreshAgents.p diff --git a/PAS/Management/OEManager/ABL/reset.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/reset.p similarity index 100% rename from PAS/Management/OEManager/ABL/reset.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/reset.p diff --git a/PAS/Management/OEManager/ABL/stopAgents.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/stopAgents.p similarity index 100% rename from PAS/Management/OEManager/ABL/stopAgents.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/stopAgents.p diff --git a/PAS/Management/OEManager/ABL/trimABLSession.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimABLSession.p similarity index 100% rename from PAS/Management/OEManager/ABL/trimABLSession.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimABLSession.p diff --git a/PAS/Management/OEManager/ABL/trimABLSessions.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimABLSessions.p similarity index 100% rename from PAS/Management/OEManager/ABL/trimABLSessions.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimABLSessions.p diff --git a/PAS/Management/OEManager/ABL/trimABLSessionsTest.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimABLSessionsTest.p similarity index 100% rename from PAS/Management/OEManager/ABL/trimABLSessionsTest.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimABLSessionsTest.p diff --git a/PAS/Management/OEManager/ABL/trimSessMgrSessions.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimSessMgrSessions.p similarity index 100% rename from PAS/Management/OEManager/ABL/trimSessMgrSessions.p rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/trimSessMgrSessions.p diff --git a/PAS/Management/OEManager/ABL/OpenEdge/ApplicationServer/Util/OEManagerConnection.cls b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Util/OEManagerConnection.cls similarity index 100% rename from PAS/Management/OEManager/ABL/OpenEdge/ApplicationServer/Util/OEManagerConnection.cls rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Util/OEManagerConnection.cls diff --git a/PAS/Management/OEManager/ABL/OpenEdge/ApplicationServer/Util/OEManagerEndpoint.cls b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Util/OEManagerEndpoint.cls similarity index 100% rename from PAS/Management/OEManager/ABL/OpenEdge/ApplicationServer/Util/OEManagerEndpoint.cls rename to PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Util/OEManagerEndpoint.cls diff --git a/PAS/Management/OEManager/ABL/utils.zip b/PAS/Management/OEManager/ABL/utils.zip new file mode 100644 index 0000000..0cf119e Binary files /dev/null and b/PAS/Management/OEManager/ABL/utils.zip differ