Omnis Technical Note TNWE0016 Dec 2007

Direct HTTP access in Omnis

Omnis Studio 4.2 or above
By Götz Krija

The so-called Omnis "Ultra-thin" Client technology allows you to call an Omnis Studio remote task from within an HTML form without using the JavaScript Client in the browser. The parameters and data are sent via the Omnis Web Server plug-in (e.g. omnisapi.dll for IIS web servers), which must be located in a certain folder on your web server (usually in the cgi or scripts folder). Omnis creates an instance of the particular remote task and executes its $construct() method. The return value then has to be plain HTML text.

Howver, since version 4.2 Omnis Studio includes its own built-in web server, which means you can communicate with Omnis directly via HTTP, without the need to install a separate "real" web server (such as Apache, or IIS) or the web server plug-in supplied with Omnis (note the built-in http server does not support HTTPS). Using the built-in http server may be a convenient way to test an Omnis Ultra-thin application, where the only difference is the format of the http call itself to Omnis - in all other respects your application, including the code in your remote tasks, is the same.

The diret http call to Omnis is structured like this:

http://<Server>:<Serverport>/Ultra

<Server> is the domain name or the IP address of the computer on which Omnis Studio is running. This is often 127.0.0.1 for your own local machine, but will be configured using a different address or server name on a remote server.

<Serverport> is the port number which has been set in $serverport of Omnis Studio; this is 5912 by default, but you can change it to anything you wish, in the range 1-32767. The $serverport property is an Omnis preference ($root.$prefs).

To try this out, create a library called "DirectHTTP" and add a remote task called "rtDirectHTTP". Then insert the following code into the $construct() method of the remote task:

; $construct() method
; create the following variables
; Parameter var: pParams (Row)
; Local vars: fullhtml (Char 100000000) & html (Char 100000000)

Begin text block
Text: <html> (Carriage return,Linefeed)
Text: <body bgcolor="FFFFFF"> (Carriage return,Linefeed)
Text: <title>Hello [pParams.User] </title> (Carriage return,Linefeed)
Text: <H1>Hello [pParams.User] </H1> (Carriage return,Linefeed)
Text: <a href="javascript:history.go(-1);">Go back</a> (Carriage return,Linefeed)
Text: </BODY> (Carriage return,Linefeed)
Text: </html> (Carriage return,Linefeed)
End text block
Get text block html
Calculate fullhtml as con('content-type: text/html',chr(13,10),'content-length: ',len(html),chr(13,10,13,10),html)
Quit method fullhtml

The Remote task can be called within an HTML form with the following source text:

<html>
<form action="http://127.0.0.1:5912/ultra" method="Get">
What is your name? <input type="Text" name="User" size="30" maxlength="50"></br></br>
<input type="Submit" name="Send" value="Send">
<input type="hidden" name="OmnisLibrary" value="DirectHTTP">
<input type="hidden" name="OmnisClass" value="rtDirectHTTP">
</form>
</html>

You must change the IP address and the port 5912 according to your configuration, although the IP address and port number given above are the default values.

Then open the HTML form in a browser, enter a name in the field, and click Send.

This will call the $construct method in the remote task "rtDirectHTTP", passing a parameter called "User" to it, which will contain the text you entered in the form. The full http call is like this:

http://127.0.0.1:5912/ultra?User=Santa&Send=Send&
  OmnisLibrary=DirectHTTP&OmnisClass=rtDirectHTTP

The remote task processes the form values (and performs whatever other functions you like), and returns standard HTML text that is displayed in the browser, something like this:

Hello pic

Download the sample library and html page: direct_http.zip

You need to open the sample library in Omnis Studio (version 4.2 or above) and leave it running. Then open the enclosed html file from any location on your computer.