OEngineServer Configuration and Specifications


Configuring your OEngineServer port

By default the OEngineServer is configured to listen on port 8088.  You can change this port by editing the eserver.cfg file located in your OpenInsight directory.

The contents of the eserver.cfg file are as follows:

// configuration file for oesocketserver.jar
// invocation:
// java - jar oesocketserver.jar {-l <configfilename>} {-d {<debuglevel: 1/2/3/etc.>}} {-o <debugFileName>}  {-u <debugDetailFlag: 0/1>} {-v} {-i}
//
// which port to listen on
PortNumber=8088
// maximum number of sockets connected at any time (0=unlimited)
MaxConnections=0
// maximum number of engines to keep in queue (for stateless connections ONLY)
MaxEngines=10
// time (in minutes) to wait before killing idle engines from queue
IdleTimeout=15
// time (in seconds) to check on idle engines (and to run 'timer proc', if any)
IdleCheck=60
// maximum time (in minutes) to keep an engine in memory before shutting it down (0==no maximum)
MaxUpTime=0
// maximum time (in minutes) to allow an engine to run a single process before considering it "stuck" and shutting it down (0=no maximum)
MaxRunTime=0

// Routine(s) to run at periodic intervals
// SystemMonitor: <routinename>,<appname>,<username>,<password>{;<routinename>,<appname>,<username>,<password>{;...}}
// SystemMonitorTime: <numberofseconds_between_invocations> (default is 60)
// SystemMonitor=RTI_OEMONITOR_CLEANUP,SYSPROG,SYSPROG,SYSPROG;RTI_OEMONITOR_INDEX,SYSPROG,SYSPROG,SYSPROG
// SystemMonitorTime=60

// make this engine server a "listener" for statistics
// Statistics_Input: <port number to listen on; -1 == same as main listening port>
// Statistics_Directory: <subdirectory to put results into>
// Statistics_Days: <max number of days to keep>
//Statistics_Input=8090
//Statistics_Directory=stats
//Statistics_Days=14

// make this engine server a "generator" of statistics
// Statistics_Output: <address:port to send statistics to>
// Statistics_ID: <unique name of this engine server>
//Statistics_Output=localhost:8090
//Statistics_ID=MAIN


// List of valid directories where OEngines can be created (semicolon delimited)
// NOTE: be sure to escape the directory delimiter "\" as "\\" - for example, c:\\RevSoft\\OI
// Use "*" for "all directories are valid". If no OILocations specified, only current directory for EngineServer is valid
// Examples: OILocations=*
//           OILocations=c:\\RevSoft\\803
//           OILocations=c:\\RevSoft\\803\\;c:\\RevSoft\\801\\


// default operating mode:
// "" - JD3 mode
// 0  - block mode
// 1  - character mode
// 2  - 'stateless' block mode
Mode=
// Encoding option (defaults to 8859_1)
// Encoding=UTF8
// Control Password option (defaults to REVSOFT)
// ControlPassword=REVSOFT
// KeepAlive option (defaults to 0) - determines whether dropped, active connections
// are kept alive as "zombies" (allowing for reconnecting) or terminated
// KeepAlive=1

// Default values: may be set on per-mode, or overall, basis
// defaults for mode "" (JD3 mode)
Procedure_=JD3_LISTENER

// defaults for mode "0" (block mode)

// defaults for mode "1" (character mode)
Procedure_1=REVCMD_LISTENER

// defaults for mode "2" ('stateless' block mode)

// overall defaults

// default name of application
Application=
// default 'dispatch procedure' to run
Procedure=
// default user name
UserName=
// default password
Password=
// default engine name
Server=
// default startup flags for engine
StartupFlags=65
// default shutdown flags for engine
ShutdownFlags=1

// Default processes
// Logon the specified app/user/pwd when the OEngineServer first starts:
// AutoRun=<processname>,<appname>,<username>,<password>
// Logon the specified app/user/pwd when the first OEngineServer connection occurs:
// RunFirst=<processname>,<appname>,<username>,<password>

// Process to run for mode -1,0,2 at engine startup
StartupProc=
// Process to run for mode -1,0,2 at engine shutdown
ShutdownProc=
// Process to run for mode -1,0,2 at 'idle check'
TimerProc=

The OEngineServer included with OpenInsight 9.2.1 and above includes two new configuration keys:

MaxRunTime - the maximum amount of time (in minutes) that an engine can run before it should be considered "rogue" (or hung or crashed or dead) and shut down

MaxUpTime - the maximum amount of time (in minutes) that an engine should be left alive before it is shut down

MaxUpTime differs from IdleTimeout in that IdleTimeout will only shut down an engine that has been idle for the specified time, while MaxUpTime will shut down the engine regardless of whether it is idle or not (note that MaxUpTime will not shut down the engine _while_ it is doing some processing - it will wait until it has finished up its most recent request before shutting down the engine).

Examples of the eserver.cfg configuration settings might then be:

// how many seconds to wait between checks on the engine status (default 60) IdleCheck = 60 
// how many minutes to allow an engine to sit idle before shutting it down (default 15) IdleTimeout = 15
 // how many minutes to allow an engine to be in memory before shutting it down (default 0 = no limit) MaxUpTime = 120 
// how many minutes to allow an engine to run a single task before presuming it "stuck" and shutting it down (default 0 = no limit) MaxRunTime = 10


OEngineServer Specifications


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' REVCAP32 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 REVCAP32-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.  Examining the default, supplied eserver.cfg, we see it contains the following settings:

--------------------------------------

// configuration file for oesocketserver.jar
// invocation:
// java - jar oesocketserver.jar {-l <configfilename>} {-d {<debuglevel}}
//
// which port to listen on
PortNumber=8088
// maximum number of sockets connected at any time (0=unlimited)
MaxConnections=0
// maximum number of engines to keep in queue (for stateless connections ONLY)
MaxEngines=10
// time (in minutes) to wait before killing idle engines from queue
IdleTimeout=15
// time (in seconds) to check on idle engines (and to run 'timer proc', if any)
IdleCheck=60

// List of valid directories where OEngines can be created (semicolon delimited)
// NOTE: be sure to escape the directory delimiter "\" as "\\" - for example, c:\\RevSoft\\OI
// Use "*" for "all directories are valid". If no OILocations specified, only current directory for EngineServer is valid
// Examples: OILocations=*
//           OILocations=c:\\RevSoft\\803
//           OILocations=c:\\RevSoft\\803\\;c:\\RevSoft\\801\\


// default operating mode:
// "" - JD3 mode
// 0  - block mode
// 1  - character mode
// 2  - 'stateless' block mode
Mode=
// Encoding option (defaults to 8859_1)
// Encoding=UTF8
// Control Password option (defaults to REVSOFT)
// ControlPassword=REVSOFT
// KeepAlive option (defaults to 0) - determines whether dropped, active connections
// are kept alive as "zombies" (allowing for reconnecting) or terminated
// KeepAlive=1

// Default values: may be set on per-mode, or overall, basis
// defaults for mode "" (JD3 mode)
Procedure_=JD3_LISTENER

// defaults for mode "0" (block mode)

// defaults for mode "1" (character mode)
Procedure_1=REVCMD_LISTENER

// defaults for mode "2" ('stateless' block mode)

// overall defaults

// default name of application
Application=
// default 'dispatch procedure' to run
Procedure=
// default user name
UserName=
// default password
Password=
// default engine name
Server=
// default startup flags for engine
StartupFlags=65
// default shutdown flags for engine
ShutdownFlags=1

// Default processes
// Logon the specified app/user/pwd when the OEngineServer first starts:
// AutoRun=<processname>,<appname>,<username>,<password>
// Logon the specified app/user/pwd when the first OEngineServer connection occurs:
// RunFirst=<processname>,<appname>,<username>,<password>

// Process to run for mode -1,0,2 at engine startup
StartupProc=
// Process to run for mode -1,0,2 at engine shutdown
ShutdownProc=
// Process to run for mode -1,0,2 at 'idle check'
TimerProc=

--------------------------------------

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/AREV32 clients (using "char" mode), OECGI2/OECGI3/OIWebWizard/OI4Web (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 "installapp-nt.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 installapp-nt.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 REVCAP32 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 REVCAP32 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 REVCAP32 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>

Revelation Conference

The previous Revelation Software Users' Conference was held at the Omni Orlando Resort at Championsgate in Orlando, Florida on April 18-21, 2016.

Click Here

On The Road

Throughout the year Revelation Software attends various multivalue User Conferences as well as our Regional User Group meetings.

Click Here

International Offices

Revelation Software has various International Offices and sales regions located on multiple continents.

Click Here

Featured Clients

Revelation Software's clients are involved in every industry around the world. Here is a sampling of some of our clients and their businesses

Click Here