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.

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)

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>).

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.

The logoff command has the following format:

2<d>

The response from the EngineServer will be:

{<okcode>}0<d>

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.

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.

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>

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.

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.

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>

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.

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>

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>

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>

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>

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>

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

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

Format of request to EngineServer:

\06\1

Response from the EngineServer: List of licensed serial numbers for allowed OEngines

Format of request to EngineServer:

\06\2

Response from the EngineServer: @FM/@VM delimited list of currently running engines and their status

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

Format of request to EngineServer:

\06\4

Response from the EngineServer: <version><space><servername>

Format of request to EngineServer:

\06\5

Response from the EngineServer: @VM-delimited list of printers

Format of request to EngineServer:

\06\6

Response from the EngineServer: "0" (if the OEngine is not a phantom), or "1"

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>