Technical Configuration for CTO
The CTO (Character to OpenInsight) environment is designed to emulate a traditional multivalue ‘green screen’ environment. It is one of several user interfaces that interact with the OpenInsight OEngine Server.
Requests from various user interfaces are sent, via tcp/ip, to the central “OEngine Server” (which must be run in the same directory as OpenInsight). The OEngine Server is responsible both for communicating with the user interfaces, and for creating, communicating with, and shutting down OpenInsight’s OpenEngine. The OEngine Server also manages “caching” of OpenEngines, for efficient performance in non-persistent applications (ie, web requests).
The OEngineServer can be run either as a service, or through a command-line interface. Note that the OEngineServer, as a java application, requires that the latest java runtime be installed on the same machine as OpenInsight.
To run the OEngineServer on the command line, issue the command “java –jar oesocketserver.jar” in the OpenInsight directory. Note that you may need to more fully describe the path to the java executable on some systems. If desired, you may add an optional parameter (“-d 1”) to display some debugging output. To terminate the command-line version, type ^C to stop the OEngineServer.
To run the OEngineServer as a service, you must run the command InstallApp.bat in the OEServer subdirectory of your OpenInsight directory. Note that this _installs_ the service, but does not initially start it; use the Services applet in Windows to actually start the service, or reboot your system to have the OEngineServer service automatically start.
The OEngineServer reads configuration information from the file “eserver.cfg”, also located in your OpenInsight directory. You may modify its default behaviour by changing the settings in this file. The default values in this file are initially set as follows:
// 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
// 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 WINWIN)
// ControlPassword=WINWIN
// 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
All values are described with comments, and should be self-explanatory. Note that changing any values in the eserver.cfg file will require that you restart the OEngineServer (either by stopping and restarting the command line, or stopping and restarting the service, as appropriate).
A telnet server has also been created to allow remote users to access the OEngineServer functionality. Please note that currently the OETelnetServer only supports the following terminal types: VT100, ansi, xterm
The OETelnetServer may also be invoked via a command line, or started as a service. To run on the command line, specify the command “java –jar oetelnetserver.jar” from within the OpenInsight directory. To terminate the command-line instance of the telnet server, type ^C.
To run as a service, you must first run the program “InstallAppT.bat” in the OEServer subdirectory of your OpenInsight directory. Note that this _installs_ the service, but does not initially start it; use the Services applet in Windows to actually start the service, or reboot your system to have the OETelnetServer service automatically start.
The OETelnetServer reads configuration information from the file “oetelnetserver.properties”, also located in your OpenInsight directory. You may modify its default behaviour by changing the settings in this file. The default values in this file are initially set as follows:
#Unified telnet proxy properties #Daemon configuration example. #Created: 15/11/2004 wimpi #Modified: 10/01/2005 bzs ############################ # Telnet daemon properties # ############################ ##################### # Terminals Section # ##################### # List of terminals available and defined below terminals=vt100,ansi,windoof,xterm # vt100 implementation and aliases term.vt100.class=net.wimpi.telnetd.io.terminal.vt100 term.vt100.aliases=default,vt100-am,vt102,dec-vt100 # ansi implementation and aliases term.ansi.class=net.wimpi.telnetd.io.terminal.ansi term.ansi.aliases=color-xterm,xterm-color,vt320,vt220,linux,screen # windoof implementation and aliases term.windoof.class=net.wimpi.telnetd.io.terminal.Windoof term.windoof.aliases= # xterm implementation and aliases term.xterm.class=net.wimpi.telnetd.io.terminal.xterm term.xterm.aliases= ################## # Shells Section # ################## # List of shells available and defined below shells=RevShell # shell implementations shell.RevShell.class=net.wimpi.telnetd.shell.RevShell ################## # Tuning Section # ################## tune.delay=0 ##################### # Listeners Section # ##################### #example: listeners=std,port2,port3 listeners=std # std listener specific properties #Basic listener and connection management settings std.port=23 std.floodprotection=5 std.maxcon=25 std.servername=localhost std.serverport=8088 # Timeout Settings for connections (ms) std.time_to_warning=3600000 std.time_to_timedout=60000 # Housekeeping thread active every 1 secs std.housekeepinginterval=1000 std.inputmode=character # Login shell std.loginshell=RevShell # Connection filter class std.connectionfilter=none # EXAMPLE: port2 listener specific properties #Basic listener and connection management settings port2.port=2023 port2.floodprotection=5 port2.maxcon=1 port2.servername=localhost port2.serverport=8089 # Timeout Settings for connections (ms) port2.time_to_warning=3600000 port2.time_to_timedout=60000 # Housekeeping thread active every 1 secs port2.housekeepinginterval=1000 port2.inputmode=character # Login shell port2.loginshell=RevShell # Connection filter class port2.connectionfilter=none # EXAMPLE: port3 listener specific properties #Basic listener and connection management settings port3.port=2024 port3.floodprotection=5 port3.maxcon=25 port3.servername=localhost port3.serverport=8089 # Timeout Settings for connections (ms) port3.time_to_warning=3600000 port3.time_to_timedout=60000 # Housekeeping thread active every 1 secs port3.housekeepinginterval=1000 port3.inputmode=character # Login shell port3.loginshell=RevShell # Connection filter class std.connectionfilter=none
You may specify one or more “listeners”, which the OETelnetServer uses to listen on various ports. By default, port 23 is used by the “std” listener, though the configuration file also shows how you could configure multiple listeners on other ports. The properties that you may wish to set include:
Port: the tcp/ip port where the telnet server will “listen” for requests
Maxcon: the maximum number of simultaneous connections
Servername: the ip address or name of the OEngineServer the telnet server should communicate with
Serverport: the tcp/ip port of the OEngineServer the telnet server should communicate with
Application: the default application to connect to
UserName: the default username to connect as
Password: the default password to use for connecting
If you configure additional listeners, and set the MAXCON property for a listener to 1, when a user connects to that specific listener, the telnet server will use that listener name as the “process number” in the CTO environment. In this way, it is possible to explicitly control which “process number” each telnet user is assigned to by specifying these alternate telnet port listeners.
For each listener, you may set various properties by prefixing the name of the listener to the property name (ie, “std.serverport”, “std.servername”, etc.). Note that by setting the various default information for application, username, and password, you can configure either full or partial “auto-connect” into an OpenInsight CTO application.
Local users can interact with the OEngineServer through the “REVCMD” (Revelation Command Line) interface. This is available either as a complete standalone routine (REVCMD.EXE), as a standalone OI form (CTO_STANDALONE_FORM), or as an OI “component” which can be included in other GUI forms (CTO_CHILD_FORM).
When run as a standalone routine, the REVCMD.EXE has the following command-line options:
-a <applicationname>
-u <username>
-p <password>
-e <hostaddress>
-n <hostport>
-r <routine to run>
-s <enginename>
-f <startupflags>
-d <shutdownflags>
-w
The –a, -u, and –p parameters allow you to “auto-login” to the specified OI application; if set, they will cause REVCMD.EXE to skip prompting for the application, user name, and/or password. The –e allows you to specify the ip address or name of the OEngineServer (the default is “localhost”); the –n allows you to specify the tcp/ip port of the OEngineServer (the default is 8088). The –r parameter allows you to specify the name of a routine to run when first logging in; if the –w option is specified, then REVCMD.EXE will wait until this routine has terminated, and then disconnect. The –s option allows you to specify a specific engine name to connect to, and the –f and –d parameters allow you to define specific startup and shutdown flags used by the OEngineServer.
Any values that are not set will assume the ‘default’ values as specified in the eserver.cfg file for the OEngineServer, with the exception of username, password, and application; these will be prompted for. If the user enters <return> for any of these values, then the defaults (if any) from the eserver.cfg file will be used.
Note that you can configure each REVCMD session so that it has a specific “process number” in the CTO environment by explicitly passing in the desired process number as the “engine name” parameter (as specified with the –s flag). The engine name should be unique, and should begin with \\.\(for example, \\.\10 will instruct CTO to define this connection as process number 10).
When run as a standalone OI form, the CTO_STANDALONE_FORM combines, in order, the record CTO in the SYSENV table, the record CTO in the MD table of the current application, and the record CTO*<current user name> in the MD table of the current application, to determine its behaviour. This allows for user-level, application-level, and system-level configuration of the interface. The record in all three locations has the following layout:
<1> IP address or name of OEngineServer (default is localhost), or path to revcap32.dll
<2> TCP/IP port of OEngineServer (default is 8088)
<3> foreground color name (default is GREEN)
<4> background color name (default is BLACK)
<5> title (default is OpenInsight Character Interface: <appname>)
<6> program to run (default is none)
<7> font name
The CTO_STANDALONE_FORM, when invoked, will log in to the current application, with the current username and password, and then (if specified) run the program defined in field 6 of the configuration record, and then terminate. If no program is defined in field 6, then ‘normal’ processing will result (ie, if a login proc/paragraph/command is found, then it will be run, otherwise the user will be left at TCL)
When run as an OI component, users may configure properties of the CTO_CHILD_FORM either in the form designer, or via SET_PROPERTY calls in the CTO_CHILD_FORM commuter module. Other GUI elements can interact with the CTO_CHILD_FORM by the use of the following subroutines from your character programs: CTO_DIALOG_BOX, CTO_GUI_FUNCTION, CTO_GUI_SUBROUTINE, CTO_MSG, CTO_POPUP, CTO_RUNWIN and CTO_SET_PRINTER.