Connected( ) Behavior in PAS for OpenEdge
Connected() is a method on the server object handle that returns TRUE if a PAS for OpenEdge instance is currently connected and associated with the server handle. On the initial client connection, the Session Manager component in PAS for OpenEdge creates a session for the client. This session is assigned a unique identifier that is exchanged between the Session Manager and the client on all future HTTP requests. This article defines the behavior of the CONNECTED( ) method across the OpenEdge 12 releases for all clients: Windows (prowin, prowin32), character (_progres), PAS for OpenEdge (_mproapsv), .NET OpenClient, Java OpenClient and WebClient.
Default CONNECTED Behavior (11.5 – 12.2.4)
CONNECTED( ) returns a logical value indicating whether the client made a successful connection to an ABL Session in a PAS for OpenEdge instance at any time in the past. It does not do any subsequent communication with the server to check if the connection is still valid. Unfortunately, this means CONNECTED( ) will always return TRUE after an initial connection even if the server is shut down. While this behavior was backward compatible it did not provide the required functionality to validate all of the connection points in the complex architecture of PAS for OpenEdge. Both the client and the server must be the same OpenEdge version.
Enhanced CONNECTED Behavior (12.2.5+)
CONNECTED( ) returns a logical value indicating whether a Session Manager session is available to handle requests from the client. This implies that the client has made a successful CONNECT() call. To check if the connection is active, the client sends a HTTP HEAD request to the server with the session identifier the client received when it first connected to the PAS for OpenEdge instance. The following property values are required to get the enhanced connected behavior:
- useHTTPSessions must be set to 1
- useEnhancedConnected must be set to 1 (in 12.2.5+ only)
- enableRequestChunking equal to 1 is recommended since it improves performance
Note: Both the client and the server must be the same OpenEdge version.
CONNECTED( ) will return TRUE if the session manager can reach a session with the session identifier. When the session receives the connected inquiry, the Session Manager session running time is reset to 0, like with any other client request. This affects the idleSessionTimeout and HTTPSessionTimeout values for this single session. When connected is called independently from a request to run ABL code, this can be used as a keep-alive feature.
CONNECTED( ) will return FALSE when the client 1) cannot reach the server or 2) the PAS for OpenEdge session manager cannot find a session with the identifier passed in from the client. When FALSE is returned, the client will mark the connection as “unavailable” and will never check the servers state again for this session. Note the server outage may NOT be persistent, in the case of intermittent HTTP errors (stateless protocol), but once the connection is marked as invalid by the client, it is marked as invalid and can no longer be used. Fault tolerance logic is expected to manage a client reconnect in this case.
Steps to enable usage of Enhanced CONNECTED behavior in 12.2.5+
- Configure the useEnhancedConnected property in openedge.properties under the APSV section
Values
- If useEnhancedConnected=0, the CONNECTED() method returns TRUE once a valid http connection has been made
- If useEnhancedConnected=1, the CONNECTED() method returns TRUE when there is valid session manager session available
Related Properties
- useHTTPSessions must be set to 1
- enableRequestChunking equal to 1 is recommended since it improves performance
Example (openedge.properties):
[<ablappname>.<webapp>.APSV]
adapterEnabled=1
enableRequestChunking=1
oepingEnabled=0
oepingProcedure=
useEnhancedConnected=1
useHTTPSessions=1
Please note that the useEnhancedConnected switch is only valid in OpenEdge version 12.2.5+, where it allows for selective activation and deactivation of the behavior. In OpenEdge version 12.5 and later, useEnhancedConnected is the default, and the CONNECTED/2.0 server header in response is always seen.
- Update oeablsecurity.csv file in all the webapps (This step is only necessary if connections use https to connect to pasoe):
- For all login models except the "container" model add or uncomment:
"/apsv/**","OPTIONS","hasAnyRole('ROLE_PSCUser')"
- For the "container" login model add or uncomment:
"/apsv/**","OPTIONS","hasAnyRole('ROLE_PSCUser','ROLE_ANONYMOUS')"
Notes:
- If a load balancer is used, configure the ‘main proxy configuration directive’ value to “apsv” ( example for Apache HTTP Server: ProxyPass"/apsv" )
- Instances created after 12.2.5 update will automatically have the lines in the oeablsecurity.csv file, but for existing instances running https, those lines need to be added.
- For instances created after 12.2.5, and before 12.3, this behavior still needs to be enabled by setting useEnhancedConnected=1 in openedge.properties.
How to determine if Enhanced CONNECTED is enabled (12.2.5+)
- HEAD messages in the localhost-access log
When Enhanced CONNECTED is enabled you will see HEAD messages in the <instance-dir>/logs/localhost-access.<date>.log file when the CONNECTED() method is used.
For example:
"HEAD /apsv/_connected HTTP/1.1" 200 - ROOT:a:0000004d
While other HEAD messages may be seen without this feature, the HEAD /apsv/_connected message can only ever be seen if the feature is enabled.
- Use curl or any other HTTP client to send an HTTP OPTIONS request
For example:
curl http://localhost:8810/apsv -i -X OPTIONS
If it includes the Server header "CONNECTED/2.0", then useEnhancedConnected is enabled. For example:
HTTP/1.1 200
Transfer-Encoding: chunked
Allow: GET,HEAD,OPTIONS,POST
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Type: application/octet-stream
Date: Tue, 12 Apr 2022 14:43:54 GMT
Expires: 0
Pragma: no-cache
Server: CONNECTED/2.0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Xss-Protection: 1; mode=block
Content-Length: 0
- Use OEJMX or oemanager REST API to "getProperties" from the agent to see how the property was set.
For the oemanager REST API, follow the instructions in the following article:
How to get the properties of an agent using OE Manager's REST API?For OEJMX:
Write the following query and save it as getProperties.qry:
{"O":"PASOE:type=OEManager,name=AgentManager","M":["getProperties","<agent-id or agent-pid>"]}
To execute the query:
<instance-dir>/bin/oejmx.sh -R -Q <input-query-path\file> -O <output-path\file>
- Test it. Connect to the AppServer from the ABL and test the CONNECTED() method.
From the Procedure Editor, run the below code
DEFINE VARIABLE iCount AS INTEGER NO-UNDO.
DEFINE VARIABLE hAs AS HANDLE NO-UNDO.
PAUSE 0 BEFORE-HIDE.
CREATE SERVER hAs.
hAs:CONNECT("-URL http://<host>:<port>/apsv").
DO WHILE TRUE:
iCount = iCount + 1.
MESSAGE hAs:CONNECTED() " count: " iCount.
PAUSE 2 NO-MESSAGE.
END.
While the above code is running, stop PASOE. (e.g. <instance>/bin/tcman stop). If no errors occur, the Enhanced CONNECTED is NOT enabled.
