Setting up REST in OI#

This document is my quick hack in configuring my laptop with / to support REST into OI. Once you configure all the pieces up, it's really quite satisfying the performance. You effectively open up our antiquated OI apps to the real web.

This doc is dated 18.09.18 - Rev indicate a new download of OECGI4 for OpenInsight 9.4 released. The attached .pdf file details how to install and setup internet II server for windows, and in most part is easy to follow. There's parts that are just difficult, however read online articles and you'll trip through it.

You need to appreciate that OECGI4 was not destined for OI9.4 (if I got my facts correct) under generic licencing arrangements, however, it does have lots of excellent impovements over OECGI3.

So, this brief doc will reflect on my install of this version of the code.

Installing OECGI4 to OI9.4#

  1. install the IIS server, and configure it up (follow the install instructions in the official Rev instructions .pdf file)
  2. Setup the oeserver (NT service) or as i did locally the oesocketserver thing
  3. Connect up IIS and oengine / oesocketserver, test the interface
  4. Create your OI REST entry point

One of the things I noticed in the .zip downloaded was the .reg file with the hive setup for OECGI4. It appears to be 32-bit, however, I'm sure that my 64-bit windows needed the 'WOW64' bit version. I'll drop samples of both files at the end of the article.

However, to their credit there's this note right on the download page noted above:

  • Also, its registry settings will be contained in the normal registry tree (at HKEY_LOCAL_MACHINE\SOFTWARE\REVSOFT\OECGI4) rather than in the 32/64 subtree (HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432NODE\REVSOFT\OECGI4).

Configuration files#

Programming for REST#

If you're familiar with REST, you'll know that the buzz is all about coding /api style. To achieve this in IIS and the kludge into OECGI4, you'll need to exec the following in the IIS configuration.

We've undertaken the SRP HTTP-thing as the basis of our development, so contact SRP and get the framework. Everything after that is very simple, and we're more than happy to share any knowledge and code.

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\RevSoft\OECGI4]
    "ApplicationName"="MMS"
    "EngineName"=""
    "FileMode"="2"
    "FilePath"=""
    "OILocation"=""
    "ProcedureName"="NV_HTTP_MCP"
    "ServerPort"="8088"
    "ServerURL"="127.0.0.1"
    "ShutdownFlags"="1"
    "StartupFlags"="65"
    "SysDownPage"=""
    "UserName"="MMS"
    "UserPassword"="PASSWORD"
    "AdditionalValues"="HTTP_AUTHORIZATION,HTTP_MEDIA_TYPE,HTTP_ACCEPT_ENCODING,HTTP_ACCEPT_CHARSET,HTTP_ACCEPT_LANGUAGE"

Programming & testing REST#

Generally to test your code, you'd have to go the whole hog of setting up the web interface, then place a debug in your OI code, run a web request, and fumble till you get things done. Very painful. A quick important aside: When you run up oesocketserver, it appears to grab the object code of your OI, so if you make changes to your OI code, more than likely you'll have to re-start oesocketserver every time you do so as to flush the cache.

Below is my java-path.cmd file, which I have to run as a hack because OI 9.4 uses 32 bit java, however, my windows 10 laptop is 64bit, so I have this hack (works perfectly, other than i don't do the software patches).

"C:\Program Files (x86)\Java\jre1.8.0_181\bin\java" -jar oesocketserver.jar -d 99

Because of this hack, when setting up OESERVER (windows service), I've had to also hack the file \oeserver\conf\wrapper.cfg, with the following to point to the same 32-bit executable.

#********************************************************************
# Wrapper Properties
#********************************************************************
# Java Application
wrapper.java.command=C:\Program Files (x86)\Java\jre1.8.0_181\bin\java

However, this is how I debug without going through the web.

Web Test Harness#

Firstly, you must capture the 'request' object that comes from the web, and the simplest means it to grab it and then write it away to SYSLISTS or some other file you're comfortable with. From there, you simply read that 'request' in and manipulate your OI / REST code through the editor. Here's what my code looks like:

compile function test_nv_http_mcp( void )
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//
// This program is proprietary and is not to be used by or disclosed to others,
// nor is it to be copied without written permission from Envizion Systems Pty Ltd.
//
// Name       :
//
// Description: REST test harness.
//
// * @package   PowerForce
// * @author    Martin Drenovac (for Envizion Systems Pty Ltd)
// * @copyright Copyright (c) 2007 - @present, Envizion Systems Pty Ltd
// * @licence   http://powerforcesoftware.com/user/license.html
// * @link      http://powerforcesoftware.com
// * @since     Version 1.0
//
// History (Date, Initials, Notes)
// 14/09/18 mpd Original programmer
//
// Date: 2018/09/14 17:34:22 +1000 (Fri 14 Sep 2018)
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
#PRAGMA OUTPUT SYSLISTS mpd_test_nv_http_mcp

$INSERT nv_copyright
$INSERT nv_userprefs

DECLARE function    nv_error,   nv_utils,   nv_http_mcp
DECLARE subroutine  check_assignments
check_assignments( void )

nv_version$$    = "[ver: i257]"
retval          = ""


file$$      = "SYSLISTS"
OPEN "", file$$ TO sl$f ELSE
    RETURN nv_error("XF07", nv_utils("OPEN", file$$))
END

READ request FROM sl$f, "HTTP-MCP-REQUEST" THEN
// this is where I stored a sample 'request' coming in from IIS.
// which then allows me to use it without actually going to the web every test
END ELSE
    DEBUG
END

error= ""
void = nv_http_mcp(request, error)
//
// next two lines as just so that I can see the reply in OI using the editor, otherwise the response is oengine
// big string
//
SWAP \0D0A\ WITH @FM IN void
SWAP \0A\ WITH @VM in void
debug
RETURN retval

The call to 'nv_http_mcp' is the SRP function that you'll get with the framework. The point is, is that it will act as if it's getting the 'request' from a browser, alas no - it's from your editor, and voila you debug internet code till you get it right. If you need to change parameters of your call, either manually hack the reqest record or if you're super keen, programatically manipulate it here locally once you've read it in.

I can't drop the nv_http_mcp code here as it's proprietary to SRP, and they're good blokes, so buy the framework.

my hive for local testing sample web request from IIS

download 32 bit version of java (OI 9.x)#

Instant Client Downloads for Microsoft Windows 32-bitJava SE Runtime Environment 8 Downloads