Configuring Your OpenInsight Server

When a request has been received by the web server, and submitted to the OpenInsight server via OECGI4, the host “listener” routine validates the request and invokes whatever user-specified stored procedure has been requested. In normal use, the listener routine is the Revelation Software provided stored procedure RUN_OECGI_REQUEST.

OECGI security, when running the default RUN_OECGI_REQUEST “listener” routine, is controlled by a record located in the SYSENV table named CFG_INET. CFG_INET contains settings for which security, "wrapup", and abort routines (if any) should be used in OECGI requests.

The CFG_INET record can be set on a per-user, per-application, or system-wide basis. OpenInsight first looks for a record named CFG_INET*<appname>*<username> (for example, CFG_INET*EXAMPLES*JOHNSMITH); if this record is found for the current application and user name, its contents are used. If no CFG_INET*<appname>*<username> record is found, OpenInsight then searches for a record named CFG_INET**<username> (for example, CFG_INET**JOHNSMITH); if this record is not found, then CFG_INET*<appname> (for example, CFG_INET*EXAMPLES) is checked. If no matching username or application specific records are found, then the system-wide CFG_INET record is used. In this fashion, it is possible to have multiple independent OECGI configurations operating on a single system, and OpenInsight will use the most "specific" one it can find.

The first field of the configuration record contains three values. The first value of the first field of the CFG_INET record contains the name of the security routine; in normal use, it defaults to INET_SECURITY. The second value of the first field contains the name of the “wrapup”, or finalize, routine; it defaults to INET_FINALIZE. The third value of the first field contains the name of the “abort” routine; it defaults to INET_ABORT.

The second field contains the text to return if no data is returned after processing the request. If desired, the string “%query%” can be used in the text to indicate the original calling URL, and @VMs can be placed within the text to generate multiple lines of output.

The third field contains the optional extension to be removed from the cgi request (for example, “.CGI”); this is normally left blank.

The fourth field contains the optional default path to substitute in the request string, if CGI parsing by the web server has invalidated the expected response; this is normally left blank.

The fifth field contains the @vm delimited “white list” of INET_programs. By default this field is blank but you should add INET_TRACE and INET_TEST_CONNECT in order to test your connection.

Once the RUN_OECGI_REQUEST routine has parsed the proper configuration record, it does not re-read that record so long as the engine continues running; changes to the configuration record, therefore, must be made before any requests are submitted, or the engine server must be stopped and restarted so that all engines are reloaded.

Before the user-requested stored procedure is invoked, RUN_OECGI_REQUEST will verify that it is a valid procedure by calling the specified security function (INET_SECURITY by default). This routine will take two parameters – the incoming request string, and the name of the user-requested stored procedure. If the user-requested stored procedure is allowed to proceed, the security function should return an empty string (“”); if the user-requested stored procedure should be prevented from running, the function should return an HTML string containing text to return to the invoking browser.

If the user-requested stored procedure does not generate any output, then the error text from the configuration record is returned; if the user-requested stored procedure does generate output without any error, then that output is passed into the finalize routine (INET_FINALIZE by default). The finalize routine takes two parameters – the incoming request string, and the output that has been generated. If required, the finalize routine may modify the output parameter.

If the user-requested stored procedure generates an error, then the abort function will be invoked (INET_ABORTED by default). The abort function has two parameters – the incoming request string, and an error indicator – and should return an HTML string containing the text to return to the invoking browser.

Note that OECGI determines if an error has occurred by checking the system status after the user-requested stored procedure has completed, via a GET_STATUS() basic+ function call. Care must therefore be taken that the user-requested stored procedure, and all of the functions and stored procedures it invokes, do not inadvertently call SET_STATUS(). Developers may wish to explicitly call SET_STATUS(0) in their finalize routine to guarantee that no “unexpected” errors are trapped by the OECGI process. Alternatively, developers can also explicitly call SET_STATUS(1, “ErrorText”) to force the OECGI process to run the “abort” function.