OpenROAD Server Components
The OpenROAD Server consists of several discrete processes that cooperatively work together.
There are three types of processes in this server:
OpenROAD Server Pooler (SPO)
The SPO is a multi-threaded process that manages access from the OpenROAD Server clients to the 4GL business logic hosted in the ASO slaves. The OpenROAD Server supports three basic methods that can be invoked by an OpenROAD Server client:
• SPO Initiate method
• SPO Release method
• SPO Call4GL method
• SPO JsonRpcRequest method
The behavior of these methods completely determines the OpenROAD Server characteristics. The SPO will process these method requests from the clients. It will either process the method internally or forward the method to the ASO slave. The description of these method behaviors in the SPO is described in the following sections.
How the SPO Initiate Method Request Works
The SPO receives an Initiate method request and performs the following processing steps:
1. The SPO checks to see if an ASO slave is already running with the same application signature as that in the Initiate request. (An application signature is the concatenation of the ImageFile value and the CmdFlags values passed in the Initiate method.)
2. If an ASO slave already exists with the same application signature, then the ASO slave UseCount is incremented and the client is bound to that ASO slave.
3. If an ASO slave does not exist with that application signature, then a new ASO slave is created and the Initiate request is forwarded to that ASO.
How the SPO Release Method Request Works
The SPO Release method can be driven explicitly by the client or implicitly when the client disconnects, exits, or times out.
The SPO receives a Release method request and performs the following processing steps:
1. The UseCount of the ASO slave associated with the client is decremented.
2. If the UseCount of the ASO slave reaches zero, then the ASO slave is scheduled for shutdown.
The OpenROAD Server Pooler is responsible for starting and stopping the ASO slave process.
How the SPO Call4GL/JsonRpcRequest Method Request Works
The client uses the Call4GL/JsonRpcRequest method to access the 4GL business logic that an OpenROAD Server hosts. It is the SPO's responsibility to validate this request and route it to the appropriate ASO slave.
The SPO receives a Call4GL/JsonRpcRequest method request and performs the following processing steps:
1. A check is made to ensure that an Initiate method request has successfully completed for that client.
2. A check is made to see if the ASO slave has been shut down because of inactivity. If it has been shut down, it will be started again using the original Initiate method parameters.
3. The Call4GL/JsonRpcRequest request is queued to the ASO slave for processing. If the application signature contains multiple ASO slaves, then the Call4GL/JsonRpcRequest request is queued to the least busy ASO slave.
4. The SPO is responsible for receiving the Call4GL/JsonRpcRequest method response from the ASO slave and routing it back to the client.
5. The SPO is also responsible to notify about any errors that the ASO slave may report. If the error is catastrophic, the SPO may shut down the ASO slave and start a new instance.
The SPO essentially acts as a router between the OpenROAD Server clients and the OpenROAD application slaves. The SPO handles multi-threaded requests from the clients and helps to ensure that requests are serialized before they are passed to the single-threaded ASOs.
OpenROAD Application Slave (ASO)
The ASO is a single-threaded process that acts as a container for the OpenROAD runtime. This process hosts the 4GL business logic and is responsible for instantiating the OpenROAD image file. Only non-visual OpenROAD runtime classes can be used in this environment.
The ASO supports the same method interface as the SPO. The methods in this interface are:
• ASO Initiate method request
• ASO Release method request
• ASO Call4GL method request
• ASO JsonRpcRequest method
The SPO is responsible for forwarding the appropriate method request to the ASO slave. ASO method behaviors are described in the following sections.
How the ASO Initiate Method Request Works
The SPO creates the ASO as a result of receiving the first SPO Initiate method request for an application signature. The SPO will forward the first Initiate request that it receives for an application signature to the ASO. Subsequent Initiate method requests from other clients with this signature are not forwarded by the SPO to the ASO.
When the ASO receives the ASO Initiate request, it will begin the OpenROAD runtime initialization for the ASO slave. The following steps are taken to process the ASO Initiate method request:
1. The ImageFile parameter of the ASO Initiate method is examined.
2. If the parameter begins with the “{” character, the value is interpreted as an application signature name (ASN) value. (An ASN is a synonym for the application ImageFile plus CmdFlags.)
3. If the ImageFile parameter does not begin with a “{” character, it is interpreted as a standard ImageFile value.
4. If the ImageFile contains an ASN, then the ASN is used to access the JSON configuration file to look up the real ImageFile and CmdFlags for this application. The ASN also is used to look up any environment variables that must be set before the OpenROAD runtime initialization starts.
5. If the ImageFile parameter contains an actual image file value, then the CmdFlags parameter in the ASO Initiate are used to supply the command flags that will be used to initiate the OpenROAD runtime. There is no provision to supply overriding environment variables when a normal ImageFile value is supplied.
6. The concatenation of the ImageFile value and the CmdFlags value determines the application signature. There is always a one-to-one correspondence between an application signature and either an ASO slave (if there is a single slave in a pool) or an ASO Slave Pool.
7. After the OpenROAD Runtime completes its initialization, if the command flags contain the -d flag, then the value specified is used to connect to the database.
8. If the -L flag is used, it supplies the name and location of the W4GL log file. The file name specified can contain the following parameter values, which are replaced at startup time:
%p
Replaced by the Process Identifier (PID)
%d
Replaced by the current date in YYYYMMDD format
%s
Replaced by the slave ID (each ASO slave started during the lifetime of the SPO is assigned a unique slave ID. For a private ASO this is 0.)
9. If the connection to the database is successful, the initialization of the ASO slave continues. If the connection to the database fails, an error is generated and control is returned to the client.
10. If there are no errors up to this point, control is passed to the starting component of the ASO slave. This component must always be an OpenROAD ghost frame. The ghost frame is where any application-specific initialization can take place.
11. When all application initialization processing is completed, the ASO slave is now initialized.
12. When the Initiate request returns control to the SPO, the ASO is ready to process Call4GL method requests.
How the ASO Release Method Request Works
The ASO Release method is sent to the ASO only when the SPO decides to shut down the ASO slave. When this request is received, the ASO slave starts its normal shutdown processing.
When the ASO slave shutdown processing is completed, the SPO is notified that the ASO is now stopped. All queued Call4GL requests are purged and the requesting clients are notified.
How the ASO Call4GL/JsonRpcRequest Methods Request Work
The OpenROAD Server clients access the 4GL business logic by using the SPO Call4GL/JsonRpcRequest method request. Because there could be hundreds or thousands of clients trying to simultaneously access an ASO slave, the SPO is responsible for serially scheduling the requests to the ASO.
When the ASO slave receives a request, control is given directly to the procedure that is referenced by either:
• The value in the ProcName parameter for Call4GL() method
• The value of the "method" member within the "request" parameter (JSON-RPC 2.0 request string) of the JsonRpcRequest method.
The procedure that is given control is generically called a Service Call Procedure (SCP). The SCP has access to any non-Visual resource contained in the image file.
When processing in the SCP is completed, control is returned to the SPO. If another request is queued to this ASO, the SPO will schedule it into the ASO.
ASO Call4GL/JsonRpcRequest requests are typically very fast. Call4GL/JsonRpcRequest requests that do not access the database typically complete in approximately 10 milliseconds (mSec). A simple singleton database request typically takes about 30 mSec. (More complicated requests take longer.)
A small number of ASO slaves can be used to support a large number of active clients. The number of clients supported depends on the size of the unit of work (UOW) for the typical transaction profile. Try to keep the UOW size consistent for each application-unique application signature. If you expect some request to have a very large UOW, it might be better to dedicate a unique ASO to process these large UOW requests.
If we assume that each transaction takes 100 mSec (two Call4GL/JsonRpcRequest requests and two database query operations), then each ASO slave could support 10 transactions per second. This equates to 600 transactions per minute. Time and motion studies imply that an active user who gets subsecond response time will generate an average of 5 transactions per minute. This means that each ASO slave could support 120 active users using a single database connection. This greatly increases the scalability of an application and reduces the resource consumption as compared to a traditional client/server application.
OpenROAD Server Controller
The SPO is started by a special OpenROAD Server client called the OpenROAD Server Controller.
Windows—orsposvc
The orsposvc process runs as a Windows service. When the service starts, this process will start up and send an Initiate request to the OpenROAD Server Pooler SPO. When the service is stopped, a shutdown message is sent to the SPO.
Linux and UNIX—orspstart and orspostop
The orspostart process runs as a daemon process. A process called orspostop will send a message to the orspostart process to cause it to shut down the SPO.
The OpenROAD Server Controller must be the first OpenROAD client to connect to the SPO. If the OpenROAD Server Controller terminates abnormally or is killed, the SPO will eventually shut down after the last client disconnects. The SPO will refuse the first connection from a client if it does not identify itself as an OpenROAD Server Controller.
