Introduction
The Revelation Software EngineServer is a java application designed to:
1. Listen (on a configurable tcp/ip port) for requests from various client applications;
2. Start up, manage, and terminate OpenEngines (OEngines) - the database engine for OpenInsight;
3. Route requests and responses from the clients to the OEngines
It manages communication with the OEngines via Revelation Softwares' REVCAPI interface (through a "Native Methods Interface"). This means that, although java is a cross-platform language and the EngineServer per se can be run on any support java platform, we are in practice limited to Windows platforms unless/until a REVCAPI-like interface is available in any other environment.
It manages communication with the various clients via tcp/ip, using a protocol first described for the "JD3" open source project. This protocol has been extensively extended for the EngineServer, but at its heart it consists of an 8 character "length" string, followed by the actual message content. The content is typically a command code, followed by a delimiter, and then any other parameters needed for that command code.
The EngineServer can also perform some operations independent of any client requests - specifically, a "startup" process, "shutdown" process, and "timer" process can be executed on any OEngines that are created, and an overal "startup" (also known as "coldstart") process can be defined to run when the EngineServer is first started.
The EngineServer is configurable via the "eserver.cfg" configuration file (located in the OI directory), which contains overall server settings as well as default settings for the various types of client connections.
The types of client connections available include:
mode -1: "JD3" (stateless, block mode communication, responding to the JD3 list of commands);
mode 0: "Block" (stateless, block mode);
mode 1: "Char" (stateful, character interaction);
mode 2: "Web" (stateless, block mode)
In addition, it is possible to create an additional type of OEngine:
[mode n/a]: "Phantom" (stateful, character interaction - must be spawned from another OEngine)
The client connection type controls how the EngineServer communicates with the OEngine, as well as what is expected of the OEngine itself. When a request comes in while in a "stateless" mode, the EngineServer looks for an OEngine with the specified "signature" (based on the app, user, password, and dispatch routine) in a queue it maintains of "available OEngines"; if one is found, then it is tasked to execute the request, and then released back into the queue. The _client_ is responsible for maintaining any required state information; _any_ of the stateless OEngines may be used to satisfy _any_ requests from _any_ client (so long as it has the required "signature"). Stateful connections, on the other hand, are dedicated to an individual client; the EngineServer maintains a 1-to-1 connection between the client and the OEngine, and thus subsequent requests from the same client will always go to the same OEngine.
The number of OEngines kept in the "available queue", as well as when OEngines should be shut down and removed from the "available queue", is configured in the eserver.cfg file. As mentioned above, it is also possible to configure routines to run at startup, shutdown, and on a "timer-like" event, for these stateless OEngines.
Revelation Software-available clients include the CTO/AREV64 clients (using "char" mode), OECGI3/OECGI4/O4W (using "web" mode), and NetOI (using "JD3" or "web" mode); the OIJio library is also available for java developers wishing to communicate with the EngineServer.
Note that the EngineServer is occasionally referred to as the "Socket Server" or "OESocketServer" interchangably.
Running the EngineServer
The EngineServer can be run from the DOS command line via the following command:
java -jar oesocketserver.jar {-l <configfilename>} {-d <debuglevel>}
where <debuglevel> is an optional number ranging from 1 to <n>; the higher the number, the more detailed information is displayed.
Revelation Software also provides a "wrapper" to enable the java command to run as a service; it is installed via the "InstallService.bat" routine located in the OESERVER subdirectory of the OpenInsight directory. This bat file reads configuration information from the wrapper.conf file located in the conf subdirectory.
Note that it is possible to run multiple EngineServer services on a single Windows system, but that to do so requires a modification to the InstallService.bat file to read a modified wrapper.conf (specifically, the wrapper.console.title, wrapper.ntservice.name, and wrapper.ntservice.displayname should be unique for each service)
Client Communication with the EngineServer
As described above, the client communicates with the EngineServer via a standard message format:
nnnnnnnncd<xxxx>
where nnnnnnnn is an 8-byte length string, c is a command character, and d is a delimiter (char(1)); if the command code requires additional parameters, these then follow the delimiter (and may be delimited as well).
The supported codes from the client for the EngineServer include:
-1 - Return list of engines
-2 - Request shutdown of engine(s)
-3 - Force shutdown of engine(s)
-4 - Spawn phantom thread
-5 - Return time of engine startup
1 - Login
2 - Logoff
3 - Execute
4 - Call
18 - Continue
19 - Input
100 - break
101 - debug
400 - call Async
Note that codes > 0 require that the OEngine be logged in to an application, otherwise an error is returned.
The EngineServer responds to the client with the same protocol (nnnnnnnn<xxxx>).
CLIENT 1 - Login Command
The Login command has the following format:
1<d><uname><d><pwd><d><appl><d><mode><d><server><d><proc><d><upflags><d><downflags><d><OILoc><d>
where <d> is char(1), <uname> is the username, <pwd> is the password, <appl> is the application name, <mode> is the type of connection desired, <proc> is the name of the OI stored procedure that will act as the "listener" or "dispatch routine", <upflags> are any startup flags, <downflags> are any shutdown flags, and <OILoc> is the directory where the desired OEngine resides.
Valid <mode> choices are "-1" (JD3), "0" (block), "1" (char), and "2" (web). Provided dispatch routines are JD3_LISTENER (for JD3 mode), REVCMD_LISTENER (for char mode), and RUN_OECGI_REQUEST (for web mode).
Default values for these can be configured in the eserver.cfg for each appropriate <mode>.
If you wish an OEngine to be started in any directory other than the current directory, then you must have that target directory listed in the eserver.cfg list of allowed directories.
If the OEngine is already logged in, this message (when in "char" mode) can be used to simulate a "logto" another application/username/password.
If the login was successful, the EngineServer response will be:
{<okcode>}0<d><engineInfo><d><engineDetails><d><expInfo><d>
If the login failed, the response will be:
{<errcode>}1<d><errMsg><d>
The <okcode> and <errcode> values ("0" and "1", respectively) will be prefixed to the message if we are running in any mode other than JD3 mode.
CLIENT 2 - Logoff Command
The logoff command has the following format:
2<d>
The response from the EngineServer will be:
{<okcode>}0<d>
CLIENT 3 - Execute Command
Invokes the previously-established "dispatch routine", passing in the specified command; in JD3 mode, also passes in the "Execute" command code. In non-JD3 mode, multiple delimited parameters are turned into comma-delimited, invidually quoted strings for the "dispatch routine"; in JD3 mode, the entire command is assembled into a single delimited string.
The execute command has the following format:
3<d><param1><d>{<param2><d>{<param3><d>...}}
The response from the EngineServer will vary depending on the message(s) generated by the OEngine.
CLIENT 4 - Call Command
Invokes the previously-established "dispatch routine", passing in the specified command; in JD3 mode, also passes in the "Call" command code. In non-JD3 mode, multiple delimited parameters are turned into comma-delimited, invidually quoted strings for the "dispatch routine"; in JD3 mode, the entire command is assembled into a single delimited string.
The call command has the following format:
4<d><param1><d>{<param2><d>{<param3><d>...}}
The response from the EngineServer will vary depending on the message(s) generated by the OEngine.
CLIENT 18 - Continue Command
This command is used when the client is responding to a "PROCESSING" message from the OEngine.
The continue command has the following format:
18<d>
The response from the EngineServer will vary depending on the message(s) generated by the OEngine, if the routine is still running; if the routine has terminated, the EngineServer responds with
{<okcode>}0<d>
CLIENT 19 - Input Command
This command is used when the client is responding to an "INFO_REQUEST" message from the OEngine.
The input command has the following format:
19<d>{<response><d>}
The response from the EngineServer will vary depending on the message(s) generated by the OEngine.
CLIENT 100 - Break Command
This instructs the EngineServer to try and halt execution of the routine that has been submitted to the OEngine.
The break command has the following format:
100<d>
The response from the EngineServer will vary depending on the message(s) generated by the OEngine.
CLIENT 101 - Debug Command
This instructs the EngineServer to try and invoke the debugger during execution of the routine that has been submitted to the OEngine.
The debug command has the following format:
101<d>
The response from the EngineServer will vary depending on the message(s) generated by the OEngine, if the routine is still running; if the routine has terminated, the EngineServer responds with
{<okcode>}0<d>
CLIENT 400 - Call Async Command (JD3 mode only)
This is identical to the "call" command, but in addition it sets the "async" flag to indicate that the client wishes to respond to any messages generated during execution of the routine that has been submitted to the OEngine. Note that it is only applicable to JD3-mode connections.
CLIENT -1 - Currently-Running Engines Command
Returns a list of the currently-running engines,and their state, either in HTML or delimited text. The format of the command is:
-1<d>{<charflag><d>}
where <charflag> is "1" if the request is coming from a "char" mode connection; in this case, the data is returned in @FM/@VM delimited strings.
If not in "char" mode, the response from the EngineServer would be:
0<d><response><d>
CLIENT -2 - Shutdown Request Command
Instructs the EngineServer to attempt to shut down the specified OEngines if they are currently "idle". The format of the shutdown request command is:
-2<d><controlpwd><d>{<param1><d>{<param2><d>...}}
where <controlpwd> is the control password (defined in the configuration file); if this is not set, or is not correct, the EngineServer response is:
1<d>Access Denied<d>
If the password is specified correctly, the additional parameters specify which OEngines should be selected for shutdown. The EngineServer then responds with:
0<d>Idle Engines shut down<d>
CLIENT -3 - Force Shutdown Command
Instructs the EngineServer to attempt to shut down the specified OEngines regardless of whether they are currently "idle". The format of the shutdown request command is:
-3<d><controlpwd><d>{<param1><d>{<param2><d>...}}
where <controlpwd> is the control password (defined in the configuration file); if this is not set, or is not correct, the EngineServer response is:
1<d>Access Denied<d>
If the password is specified correctly, the additional parameters specify which OEngines should be selected for shutdown. The EngineServer then responds with:
0<d>All Engines shut down<d>
CLIENT -4 - Phantom Logon Command
Instructs the EngineServer to start up a "phantom" OEngine (one which has no connection to any client). Any output generated by the phantom process will be discarded; any requests for input (that are not satisfied by DATA statements in basic+) will cause the phantom process to terminate.
The format of the phantom request is:
-4<d>{<addlcommands><d>{<addlcommands><d>...}}
where <addlcommands> are any additional commands to pass in to the phantom creation process. These are the same commands documented here, EXCEPT that a "sub delimiter" (char(2)) is used to delimit the pieces of the command (so as to not interfere with the top-level delimiters).
Normally, the <addlcommands> will include the login command, and the call command; for example:
-4<d>
1<sd><uname><sd><pwd><sd><appl><sd><mode><sd><server><sd><proc><sd><upflags><sd><downflags><sd><OILoc><sd><d>
3<sd><param1><sd><d>
(mode should be "3" to indicate "phantom processing).
The response from the EngineServer will be:
0<d>Phantom started<d>
CLIENT -5 - Status Info Command
This requests the time that the OEngine started, and the current time. The format of the request is:
-5<d>
The response from the EngineServer will be:
0<d>Startup: <yyyy-mm-dd hh:mm:ss>; Current <yyyy-mm-dd hh:mm:ss><d>
EngineServer Communication With The OEngine
Once the EngineServer has started an OEngine (either through a client request, or through automatic startup), it communicates with the OEngine via the REVCAPI API. Processing normally involves issuing a command through the RevSend API call, waiting for a response (either through RevPoll, if in "char" mode or if the request is the callAsync command, or through RevWait otherwise), acting on the response, and "wrapping up" when the request has finished processing.
The EngineServer will respond to the following REVCAPI messages during the RevPoll/RevWait processing:
- "UNPROCESSED" - handled internally always and processing continues;
- "PROCESSING" - If in "char" mode, or executing a callAsync command, after 10 "processing" messages, a response to the client will be sent (to enable "break" functionality); in any other situation, the EngineServer just pauses before resuming processing;
- "DATA_AVAILABLE" - If in "char" mode, or executing a callAsync command, returns any provided data to client; if in "phantom" mode, discards the data and continues processing; in any other situation, the output is accumulated until processing is complete;
- "COMPLETED"/"PROC_ERROR" - any "status text" generated by the call is retrieved, and the output returned to the client;
- "INFO_AVAILABLE" - If in "char" mode, or executing a callAsync command, returns any provided data to client; in any other situation, the output is accumulated until processing is complete;
- "INFO_REQUEST" - If a special OEngine command (see below), handled internally and processing continues; if in "char" mode or executing a callAsync command, request is sent to client; if in "phantom" mode, the phantom is terminated; in any other situation, a dummy (null) response is sent to the OEngine and processing continues
Commands From The OEngine
In addition to commands that a client might issue to the EngineServer, a stored procedure running on the OEngine, itself, may also issue specific EngineServer commands.
The command request from the Oengine is sent to the EngineServer via the INFO_REQUEST REVCAPI message, and has the following format:
<cmdindicator><cmdcode>
where <cmdindicator> is char(6), and command code is one of the values below:
1 - Return a list of serial numbers this EngineServer can support;
2 - Return a list of the currently-running OEngines;
3 - Logon a phantom process;
4 - Return the version and engine information;
5 - Return a list of printers available to the EngineServer;
6 - Return a flag if this is a phantom process;
7 - Return the time the Engine started, and the current time
OENGINE 1 - Serial Number List Command
Format of request to EngineServer:
\06\1
Response from the EngineServer: List of licensed serial numbers for allowed OEngines
OENGINE 2 - Currently-Running Engines Command
Format of request to EngineServer:
\06\2
Response from the EngineServer: @FM/@VM delimited list of currently running engines and their status
OENGINE 3 - Phantom Logon Command
Format of request to EngineServer:
\06\3{<addlcommands><d>{<addlcommands><d>...}}
where <addlcommands> are any additional commands to pass in to the phantom creation process. These are the same commands documented in the client commands section, EXCEPT that a "sub delimiter" (char(2)) is used to delimit the pieces of the command (so as to not interfere with the top-level delimiters).
Normally, the <addlcommands> will include the login command, and the call command; for example:
\06\3
1<sd><uname><sd><pwd><sd><appl><sd><mode><sd><server><sd><proc><sd><upflags><sd><downflags><sd><OILoc><sd><d>
3<sd><param1><sd><d>
(mode should be "3" to indicate "phantom processing).
The response from the EngineServer will be: Phantom started
OENGINE 4 - Version Command
Format of request to EngineServer:
\06\4
Response from the EngineServer: <version><space><servername>
OENGINE 5 - Printers Command
Format of request to EngineServer:
\06\5
Response from the EngineServer: @VM-delimited list of printers
OENGINE 6 - Phantom Flag Command
Format of request to EngineServer:
\06\6
Response from the EngineServer: "0" (if the OEngine is not a phantom), or "1"
OENGINE 7 - Status Info Command
Format of request to EngineServer:
\06\7
Response from the EngineServer: "Startup: "<yyyy-mm-dd hh:mm:ss>"; Current: "<yyyy-mm-dd hh:mm:ss>