Engine Server

eServer Management

The eServer Management – Engine Server Status Tab.

The eServer Management – Background Process Status Tab.

The eServer Management – Engine Server Output Tab. Once this is setup in eServer Configuration – Debug Tab output will display.

The eServer Management – Engine Server Output Tab with debug information.

The eServer Management – Engine Server Actions Tab. The default EngineServer Password is: REVSOFT.

From this form the system administrator can:

1. Reset idle engines

2. Reset all engines

3. Restart Engine Server

eServer Configuration

The engine server stores an encrypted password (once it has been configured) in the setting “EControlPassword”. This value is used by the OI Console version of the eServer Configuration maintenance form to validate that the user is allowed to access the routine. The default Engine Server password is: REVSOFT.

Basic configuration of the engine server allows clients to communicate (through either ANSI/ASCII or UTF8 encoding) with OEngines.

Port Number for ANSI Connections (eserver.cfg setting PortNumber): Specifies the port number the engine server will “listen” on for ASCII/ANSI requests. Default is 8088.

Enable UTF8 Connections (eserver.cfg setting UTFPort_Disabled): select whether UTF8 connections will also be allowed.

Port Number for UTF8 Connections (eserver.cfg setting UTFPortNumber): If UTF8 connections are allowed, this field specifies the port number the engine server will “listen” on for UTF8 requests.

Maximum Number of Engines (eserver.cfg setting MaxEngines): Specifies the maximum number of oengines that the engine server can start up (0=unlimited). Default is 10.

Maximum Number of Simultaneous Connections (eserver.cfg setting MaxConnections): Specifies the maximum number of simultaneous connections to the engine server (0=unlimited). Default is 0.

Idle Timeout (eserver.cfg setting IdleTimeout): Specifies the time (in minutes) after which an idle oengine will be shut down by the engine server. Default is 15.

Frequency of check for idle engines (eserver.cfg setting IdleCheck): Specifies the time (in seconds) between checks by the engine server for idle engines, MaxUpTime engines, and MaxRunTime engines. Default is 60.

Maximum time an engine should remain in memory (eserver.cfg setting MaxUpTime): Specifies the maximum amount of time (in minutes) an Oengine should be allowed to stay active in memory (not necessarily running that entire time, just not idle long enough to trigger the idle timeout when it _is_ idle). Default is 0, which means “unlimited”. Note that the idlecheck value will also be used to determine the frequency of the MaxUpTime checks.

Maximum time an engine can run a request (eserver.cfg setting MaxRunTime): Specifies the maximum amount of time (in minutes) that an oengine should be allowed to run a particular process before it’s considered “hung” and forcibly terminated. Default is 0, which means “unlimited”. Note that the idlecheck value will also be used to determine the frequency of the MaxRunTime checks.

(eserver.cfg setting MaxNumToClose): The maximum number of oengines to close at one time. Default is “0”, which is unlimited. If there are more oengines that need to be closed, they will be closed during the next idle check. This value is designed to help “stagger” the logging on and off of OEngines.

Default encoding (eserver.cfg setting Encoding): Specify the encoding used for ansi communication. The default is 8859_1. The default (8859_1) is appropriate for most sites.

Control Password (eserver.cfg setting ControlPassword): Specify the new password to use to control access to the eserver.cfg.

Keep alive abandoned engines (eserver.cfg setting KeepAlive): Set to “1” if telnet sessions that are dropped should be kept alive as “zombie processes” (with the possibility of being reattached”), or “0” if sessions that are dropped should be terminated. Note that this only applies to telnet sessions. Default value is “0”.

Allowed OpenInsight folders (eserver.cfg setting OILocations): Specifies one or more folders the engine server is allowed to start an oengine in (when a client makes a connection, it can request that the oengine be started in a different folder; that different folder must be specified in the OILocations value). An asterisk (“*”) means all locations are allowed. The default value is null, which means only the current directory is allowed.

The engine server can provide web server functionality to serve up static (HTML) and dynamic (O4W) output directly, without requiring Microsoft IIS or Apache. The web server (based on the open-source Jetty server) intentionally provides limited functionality, designed to handle the OI Console and less-heavily-loaded O4W sites with an easy to manage and configure system.

Enabled Web Server (eserver.cfg setting WebServer_Disabled): Select to enable or disable the built-in web server functionality.

Port Number for HTTP requests (eserver.cfg setting WebServerPortNumber): If the web server functionality is enabled, this is the port number on which the web server should “listen.” Default value is 18888.

Name to use in URL to identify host (eserver.cfg setting WebServerCGIProcedure): When using IIS or Apache, clients normally use OECGI3.EXE or OECGI4.EXE (or OECGI3P.PHP or OECGI4P.PHP) to initiate the CGI request that communicates between the web server and the engine server. Since, in this case, the engine server is acting as the web server, there is no actual cgi routine needed to perform the communication. However, the web server must still know when a request is for a static (HTML) page, versus a dynamic (CGI) page, so that it can be properly processed. The WebServerCGIProcedure specifies the name in the url that signifies this is a dynamic page, and thus this should be processed as though it were coming from the cgi procedure. Multiple values may be specified, semicolon delimited. By default, this value is oecgi4.exe;oecgi3.exe

Default Connection Details (eserver.cfg setting WebServerConnection_default): Specifies all the default values needed to “connect” to an OEngine. This list of settings includes application name, user name, password, startup flag, shutdown flag, “listener” routine name, engine name, OI folder, file upload mode, file upload path, and “failure page” URL. These values are identical to those used in the registry for the actual OECGI3/OECGI4.

Virtual Directories (eserver.cfg setting WebServerVirtualDirs): A list of the “virtual directories” that the web server should recognize. These are comparable to the “virtual directories” that are set up in IIS, for example. For each virtual directory, you will need to specify all the values needed to “connect” to an OEngine. This list of settings includes application name, user name, password, startup flag, shutdown flag, “listener” routine name, engine name, OI folder, file upload mode, file upload path, and “failure page” URL. These values are identical to those used in the registry for the actual OECGI3/OECGI4. In addition, you will specify the “default page” (the name of the html document to return if no specific page is specified), and the full path to the actual folder that the virtual directory represents.

The engine server can collect statistics on the requests and responses it generates. In order to prevent the collection of statistics from impacting on performance, these statistics may be processed by a different engine server (one that is not being used to handle real-time production requests, for example). Any engine server can be configured as a “receiver” of statistics information from another server, a “producer” of statistics for consumption by another engine server, or both a receiver and producer (which is most appropriate for less heavily-loaded systems).

Enable Statistics Receiver (eserver.cfg setting Statistics_Input_Disabled): Select whether or not this engine server should be able to receive statistics information.

Port Number to Use as a Statistics Listener (eserver.cfg setting Statistics_Input): If statistics receiving is enabled, this is the port number to use when acting as a statistics receiver.

Directory for Storage as a Statistics Listener (eserver.cfg setting Statistics_Directory): The directory (which may be a full path) where the statistics information will be written. The default is “stats” (ie, a relative path under the OI folder named “stats”).

Number of Days to Retain as a Statistics Listener (eserver.cfg setting Statistics_Days): The number of days of statistics information to retain. Default is 14.

Enable Statistics Production (eserver.cfg setting Statistics_Output_Disabled): Select whether or not this engine server should produce statistical information.

URL and Port Number of Listener (eserver.cfg setting Statistics_Output): If this engine server is generating statistics information, this is the URL and port number (colon-delimited) of the statistics _receiver_ this statistics _producer_ should be sending the output to.

ID to Send as a Statistics Producer (eserver.cfg setting Statistics_ID): The unique short identifier that should be used to identify the statistics coming from this engine server. This is only important if multiple engine server statistic producers are all sending their information to a single statistic receiver. Default is “01”.

The engine server can communicate with individual OpenInsight desktop clients via the “command channel.” This will allow for management of the desktop clients from the central server.

Enable Command Chat (eserver.cfg setting CommandPort_Disabled): Select whether the command port functionality is enabled.

Port Number for Command Requests (eserver.cfg setting CommandPort): The port number that will be used for the “command chat” (not yet implemented).

The engine server can run various processes automatically, for system maintenance, initialization, etc. Some of these processes run only one time (AutoRun and RunFirst), creating their own OEngines, running, and then terminating those OEngines. Others run at a specified interval (SystemMonitor), again creating their own background OEngines, running, and then terminating. Still others run in any OEngine that has been started in response to a client request (StartupProc, ShutdownProc, and TimerProc).

Settings for AutoRun (eserver.cfg setting AutoRun): If specified, this is a list of routine name, application name, user name, and password, which specifies the routine to run (and where to run that routine) when the engine server initially starts up.

Settings for RunFirst (eserver.cfg setting RunFirst): If specified, this is a list of routine name, application name, user name, and password, which specifies the routine to run (and where to run that routine) when the very first OEngine is created.

Frequency of System Monitor Processing (eserver.cfg setting SystemMonitorTime): The time (in seconds) between invocations of background processes. Default is 60.

System Monitor Processes (eserver.cfg setting SystemMonitor): list of processes to run at a regular interval (as specified in SystemMonitorTime) Each entry consists of the procedure name, application name, user name, and password (comma-delimited).

Name of Startup Routine (eserver.cfg setting StartupProc): The name of the stored procedure to run when an OEngine starts up.

Name of Shutdown Routine (eserver.cfg setting ShutdownProc): The name of the stored procedure to run when an OEngine shuts down.

Name of Timer Routine (eserver.cfg setting TimerProc) : The name of the stored procedure to run every time the “idle check” is run.

The engine server can generate more verbose output to aid in debugging and diagnostics. This information can be displayed on-screen, when the engine server is run via the java command line, or captured to a file.

Default debug level (eserver.cfg setting DebugLevel): A number indicating the amount of detail the diagnostic output should display. Higher numbers indicate more output (0=none).

Debug output file (eserver.cfg setting DebugFile): The full path and file name of the output file the diagnostic information should be recorded in.

Debug history length (eserver.cfg setting DebugHistoryLength): The maximum number of lines of output that should be stored.

O4W Configuration

O4W Configuration – Select Tab

Revelation Software, in the O4W product, provides some standard routines to perform common O4W tasks; however, these tasks may need to be modified for your individual circumstances. O4W therefore includes “hooks” where you can replace the provided routines with your own, customized stored procedures.

O4W Configuration – System Routines Tab

You may replace the following routines:

- Security authorization procedure (which verifies that users are allowed to “log in” to the O4W system, and checks that their entered password matches the password on-file). The authorization routine is a function that takes 2 parameters, the username and password as entered by the user; it returns the “permissions level” of the user, or null (“”) if the username and password were not correct

- Permissions authorization procedure (which verifies that users have permission to access a particular routine). The permissions routine is a function that takes 2 parameters, the required permissions level and the “session information” (a dynamic array containing the username in field 1); it returns 1 if the user should be allowed to execute the desired procedure, 0 if the user needs to log in, and -1 if the user should not be allowed to execute the desired procedure

- Table/Field filter procedure (which returns the list of tables, and fields within those tables, that the user can access). The filter routine is a function that takes 3 parameters, the name of the procedure that’s calling the filter, the “session information” (a dynamic array containing the username in field 1), and an optional “table name”; it returns an @VM list of tables this user should be able to select from in this procedure (if table name is null), or an @VM list of dictionary items this user should be able to select from in this procedure (if table name is not null)

- Message suffix procedure (which returns the suffix to apply to the message codes used in O4W, so that (for example) different language sets of messages can be retrieved). The message suffix procedure is a function that takes no parameters; it returns the suffix that should be appended to the message key to return the message text

- Read/Write lock procedure (which performs the “optimistic locking” that O4W uses to ensure data integrity). The read/write lock procedure is a function that takes 6 parameters: the action to perform, the table handle, the record ID, the optional record data to write (or the record that was read), the handle to use to refer to this lock, and optional extra parameters; it returns a status result (null if the operation proceeded without error)

- Default table pagination/sorting procedure (which handles pagination of table data). The pagination routine is a subroutine that has 10 parameters, and is designed to manage both pagination of table results and optional sorting of data columns within the table. Please refer to the provided source code for O4WI_TABLEPAGERLOCAL and O4WI_TABLEPAGERPLUGIN for details on how to create a pagination handler.

- Login UI procedure – If desired, developers can create their own O4W routines to replace the provided O4W login page. This option is provided so that developers can customize the user interface. Note that the replacement UI procedure should be co-ordinated with replacement security authorization and permissions authorization routines

- RSS default feed filter procedure – The O4W RSS feed provider includes the ability for each feed to be “filtered” by a stored procedure, as defined during the RSS creation process (see O4WRSSPUBLISH for details). If desired, a default filter stored procedure can be specified; feeds that do not contain a specific filter would then use this default procedure. The filter can be used to restrict which values are returned as part of the RSS feed, so that sensitive or out of date information can be removed (or alternatively so that new dynamic information can be added).

Source code for the O4WI_AUTHORIZE, O4WI_FILTER, O4WI_LOCKHANDLER, O4WI_TABLEPAGERLOCAL and O4WI_TABLEPAGERPLUGIN routines has been provided; please be sure to COPY and RENAME your modified routines if you make any custom modifications.

O4W Configuration – Scripts Tab

The Scripts tab defines the essential scripts needed for O4W to run, and the initial scripts that all O4W routines should include. The essential scripts can be obtained “on line” via Google’s hosted repository (Google Content Delivery Network, or CDN), or you can use copies of the scripts loaded on your system. Specify the source for the jQuery scripts, and if necessary override the URL or path for the files.

You must also select which version of jQuery and the jQuery User Interface (“UI”) you wish to run. Finally, you must select the theme you wish to run on your pages.

If your workstation has an external internet connection, themes can be changed by selecting the jQuery Theme dropdown list; if this is an offline connection, you must select the theme from the non-graphical list of available options.

If desired, you can add or modify the list of “standard scripts” that O4W includes in all its routines by modifying the code in the “Standard Scripts” box. This might be applicable if you wished to have another “plugin” or javascript library available to all your O4W pages.

This should be modified by advanced users ONLY.

O4W allows you to choose which graphing library should be included on your site; different graphing libraries provide different sets of graphs, and render the data in different ways. You can select the jQuery plugin “jqPlot”, the Google Visualizations library, both, or neither. Note that the jqPlot library is self-contained on your O4W system, and can be used even if no connection to the internet is available; the Google Visualizations library requires an active internet connection to function.

O4W Configuration – Mobile Tab

O4W developers can now specifically target mobile devices (cellphones and tablets); the Mobile tab allows for the specification of mobile-specific defaults. Select whether the required jQuery Mobile library should be loaded from files contained on your O4W site, or from the jQuery developers website; which version of the library should be loaded; which version of the associated “base” jQuery should be loaded; and what standard script(s) should be loaded. You may choose to configure the required scripts to minimize what is loaded, since typically mobile devices have less memory and longer loading times than desktop browsers.

O4W Configuration – Templates/Menus Tab

On the Template/Menu Management tab, you can define which template should be used as the “default” for this application. You can also specify where the templates are located, and whether this is a Windows directory or an OpenInsight table. Note that the template directory is used in the “Wizards” to allow for the selection of the templates; however, the template directory is not prefixed to the default template name, and should be specified as part of the default template if applicable.

The default mobile template may be different than the default template; the mobile template will be used when O4W is used to generate output for a mobile device (such as a cellphone or tablet). Since these devices typically have much smaller screens than the desktop browser, you should create or select a template that is more suitable to the reduced screen size.

You will also specify here what type of menu should be used by default, if the template does not specify explicitly. The “Horizontal” menu is similar to the top-line menu of an OpenInsight form or MDI frame. The “Vertical Scrolling” menu is similar to an iPod menu. The “Vertical Tree” menu is an expanding and collapsing tree menu.

If a “vertical scrolling” menu is to be displayed on your form, you may allow it to dynamically resize itself. If you select “Dynamically size vertical scrolling menu”, the vertical scrolling menu will be drawn at the most appropriate size between the minimum (if specified) and maximum (if specified) values. Note that these values, which represent the number of pixels high the vertical scrolling menu may be, should be entered as straight numbers (with no “px” indicator)

O4W Configuration – Standard Codes Tab

The O4W Form wizard allows you to specify some “standard code records” as the source of listboxes, checkboxes, and radio buttons. The Standard Codes tab allows you to add to, remove from, or alter the list of standard code records that the O4W Form wizard displays. Specify a “user friendly” name for the code record in the first column, and the name of the code record (located in the O4WCODES table) in the second column. Note that the records in the O4WCODES table must contain, in field 1, an @VM delimited list of the text to display, while field 2 contains an associated @VM delimited list of the codes associated with each display value.

O4W Configuration – Forms/Reports Tab

The Forms/Reports tab allows you to specify some O4W Form and Report-specific choices. If selected, “dynamic” reports can be automatically generated from R/List statements; specify as the URL http://<yoursite>/oecgi4.exe/O4W_RUN_REPORT?OIREPORT=<reportstatement>, where <yoursite> is the full path to your O4W directory, and <reportstatement> is the full R/List-type statement you wish to turn into an O4W Report. For example, you may specify:

http://<yoursite>/oecgi4.exe/O4W_RUN_REPORT?OIREPORT=LIST MYTABLE WITH SOMEFIELD=”1” AND WITH OTHERFIELD=”2” SOMEFIELD1 SOMEFIELD2 TOTAL SOMEFIELD3

“Dynamic” forms can be automatically generated by specifying the name of an existing OpenInsight form; specify as the URL

http://<yoursite>/oecgi4.exe/O4W_RUN_FORM?OIFORM=<formname>, where <yoursite> is the full path to your O4W directory, and <formname> is the name of an existing OpenInsight form.

If dynamic forms and reports are allowed, you may specify the permissions level needed to execute the dynamic form and report, and an O4W Form and O4W Report to use as the “template” for the dynamic form and report – the specific content of the O4W Form and O4W Report will be removed, while the menu, color, html template, etc. will be extracted for use in the dynamic output.

In order to provide the most responsive performance possible, O4W allows you to use multiple engines to generate the O4W Form or O4W Report. Each tab of the form, and each page of the report, can be “rendered” by a separate engine, allowing even very complex forms and reports to display quickly. You can specify the number of engines O4W should use for form and report generation; specify “0” for a single engine (which will generate all the tabs and pages before returning the result to the browser), or 1 or more for asynchronous rendering.

O4W Configuration – Browsers Tab

The Browsers Options tab allows you to specify minimum requirements for your O4W site. For each of the browsers, specify the minimum allowed version. You can also specify the message to be displayed, and how the message should be displayed (as a banner, a popup, or both).

Registry Settings

The OECGI4 registry settings can be modified via the Registry Settings form. Initial creation of the OECGI4 registry settings can be done by clicking on the oecgi4.reg file located in Revsoft\OInsight10\O4W directory. OECGI4 registry settings are created in Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Revsoft\OECGI4.