OI4Web (Web)
Created at 21 MAY 2008 11:24AM
OI4Web DESCRIPTION
OI4Web is a tool that allows developers to access their OpenInsight data through a web browser. While most often used with Active Server Pages (ASP), OI4Web provides an"object" that can be used in any development environment that allows for the creation and invocation of ActiveX objects.
With OI4Web, you can call an OpenInsight stored procedure and process the returned data; your ASP page can then display or utilize this data as appropriate.
The OI4Web object communicates with OpenInsight via Revelation's Engine Server technology. OI4Web communicates with the Engine Server using an 'asynchronous'connection; multiple client requests may be processed with a single, or a few, OpenInsight licenses. Also, through the use of the Engine Servers' open communication standard, it is possible to deploy the web server and OpenInsight systems on different servers.
OI4Web REQUIREMENTS
In order to use OI4Web, you must install the OI4Web setup package. In addition, you must be running a current version of OpenInsight (version 8.0.1 or above), and you must be running the Engine Server (either as a service or in 'foreground'mode).
Currently, the OI4Web software and the Engine Server will only run on Windows platforms. Although the usual configuration includes Microsoft Internet Information Server (IIS), OI4Web can potentially be used with other web server products.
OI4Web CONFIGURATION/SETUP
After installing and "unzipping" the oi4web.zip file, navigate to the folder where you have unzipped the files, and then double-click on the Setup.exe file. Alternatively, choose"Start", "Run" and type "unzipdir<\Setup.exe>
(where <unzipdir> is the full path to the folder where the files have been unzipped). Windows Installer will then prompt you for the information necessary to install OI4Web.
Once the installation has completed, you will find several files in the specified directory. The file oi4web.asp is an example Active Server Page illustrating the use of OI4Web. The file oi4web.ini is the configuration file used by OI4Web.
The OI4Web.INI file contains settings that describe how OI4Web connects to OpenInsight, and its behavior. The INI file is organized into a series of"groups", where each group has
a name, and several settings associated with that group. By allowing for multiple groups, OI4Web allows different users to access different data, or run different routines.
For example, there is a default group called GLOBAL in the included OI4WEB.INI. It contains the following information:
[GLOBAL]
EngineURL=LOCALHOST
EnginePort=8088
DatabaseName=SYSPROG
UserName=SYSPROG
UserPassword=
OiFunction=INET_XML
The name of each setting is on the left-hand side of the equal sign, and its associated value is on the right-hand side. In this example, then, the Engine URL setting has the value of LOCALHOST.
The Engine URL setting tells OI4Web where the Engine Server is running. This can be the IP address of the Engine Server machine, or LOCALHOST (if the Engine Server is running locally). The Engine Port setting defines what port the EngineServer is"listening" on; by default, this is set to 8088.
The Database Name, UserName, and UserPassword control access to the desired application. Specify the appropriate information here to access the correct application.
The OiFunction setting tells OI4Web which host routine to run when it's connected to OpenInsight. This is a "listener" routine which often processes the request sent by OI4Web further before returning results.
By default, OI4Web will access the OpenInsight database located in the same directory as the Engine Server. An optional setting, OILocation,can be specified if you wish the Engine Server to run an OpenInsight located in a different directory. Note that this feature is only available with OpenInsight 8.0.3 and above.
OI4Web USAGE
There are 4 main steps to using the oi4web object in your code:
1. Create the object;
2. Specify connection information;
3. Call the "listener" stored procedure;
4. Process the returned results
The details of these 4 steps will vary depending on the programming language selected. The oi4web.asp page contains an example of how to use the oi4web object through vbScript.
To create the object, you can use the following vbScriptcode:
setOIObject= CreateObject("Oi4Web.Server")
Once the object is created, you must specify where the oi4web.ini file (with the desired configuration settings) resides:
OIObject.iniFile="c:\OI4web\oi4web.ini"
To invoke the stored procedure in OpenInsight, you must specify the name of the group in the ini file you wish to use, and the data you wish to pass to the "listener" stored procedure:
VARIN = Request.Form
if VARIN ="" then
VARIN = Request.QueryString
end if
OIObject.OI Call VARIN,"GLOBAL"
The returned result from the "listener" stored procedure can now be accessed through the created object:
SuccessResult=OIObject.Response
The OI4Web object allows you to retrieve either the entire response, as illustrated above, or individual fields of the result. To retrieve a specific field, specify that field number, minus 1, in parenthesis in the 'response' property. For example, to retrieve the second field, your code might look like this:
Secondfield = OIObject.Response(1)
You can also retrieve the number of fields found in the response through the "DCount" property. For example,
NumFields=OIObject.DCount()
OI4Web OTHER PROPERTIES AND METHODS
While the above properties and methods describe the most common usage of the OI4Web object, there are some additional methods and properties that can be invoked if desired.
The OIConnect method requires the name of the group in the ini file you wish to use, and opens the connection to the Engine Server and logs into the specified application. Note that the OIConnect method is automatically called by the OICall method.
The OIDisconnect method is used to close the connection to the Engine Server, and log out of the specified application. Note that the OIDisconnect method is automatically called by the OICall method.
The OtherOutput property can be used to retrieve any output generated by your stored procedure that is NOT returned as a passed parameter. Like the Response property,it can be used either to retrieve the entire contents of the "out of bounds" data string (i.e., OIObject.OtherOutput)or specific fields of the data string (i.e., OIObject.OtherOutput(1)).
The OIQuery method is used as a 'management' tool to query the Engine Server about the status of the current connection. You must specify the name of the group in the ini file you wish to use to connect to the EngineServer. The results from this call will be available through the normal Response property.
The OIReset method is used as a 'management' tool to disconnect an OpenInsight session that is using the Engine Server. This may be necessary if the OpenInsight session has"crashed". You must specify the name of the group in the ini file you wish to use to connect to the Engine Server, and the "control password" defined for that Engine Server. You may also optionally specify the group name of the connection you wish to reset, and a flag that indicates whether this should be a reset "request" or a forced reset. The results of the OIReset method will be available through the normal Response property. Please contact Revelation Software for additional information if you require the use of this method.