OpenInsight Command Line Parameters

Introduction

OpenInsight provides a variety of command line parameters to customize the way OINSIGHT.exe and OENGINE.exe will launch. Since a single OpenInsight installation can support an unlimited number of applications, users, and passwords, these parameters come in handy as a way of bypassing the default login dialog boxes.

This document provides a listing of all known parameters with a description of what each one is used for. An Examples section is included near the end of this white paper. Most, but not all, of the parameters follow the same syntax:

/Parameter=Value

Whenever the documentation indicates a value of “None” is possible, this simple means no value.

OINSIGHT.exe Options

Most shortcuts will point to OINSIGHT.exe since this launches OpenInsight’s Presentation Server and allows GUI desktop applications to run.

Login Parameters

When no parameters are specified, OpenInsight presents the user with a default login dialog. This default dialog will look different based on whether or not the local computer has ever launched OpenInsight before. For computers that have never launched OpenInsight the dialog will look like this:

However, once OpenInsight has been launched at least once, the OINSIGHT.ini file will have been created in the system’s Windows directory. Within this file is information that informs OpenInsight how to launch in default mode. Here is a simple example, with the login information in red:

[Application Manager]
NCA=1
Status Bar=Yes
Ribbon=Yes
Side Tool Bar=260
SideBarToolList=2,1,3,15,5,8,16,12,13,11,14
Show Flags=No
OutLiner=*
Inherit Entities=Yes
Application=EXAMPLES
Login User=EXAMPLES
[OIPI32]
Auto Start=Yes
Auto Stop=Yes

If OpenInsight is launched again without any parameters, the information in the OINSIGHT.ini file is used and the following login dialog would appear:

This poses some problems for developers. First, this dialog does not allow the application name to be changed. End users will have to go through a few more steps in order to bring up a dialog that permits application selections. Second, since the content of the OINSIGHT.ini file is dynamic, there is no guarantee what application or user name will appear. This is particularly bothersome in an environment where multiple OpenInsight applications are used.

Developers can control the way OpenInsight login dialogs appear through the use of three login parameters.

TIP: Normally, passwords would not be passed in as a command line parameter due to the obvious security risks. However, some developers prefer to use their own application based security. Using /PW with generic users will bypass the login dialog altogether. Alternatively, users with no passwords can be used.

Developer Parameter

When Runtime Class licenses are used, OpenInsight application will always launch in runtime mode regardless of any parameters used. If the license supports development access to the system (e.g. Developer Class or Works licenses) then the application can be launched in either development or runtime mode, but runtime mode is assumed if no special parameters are used. In order to launch OpenInsight in an explicit mode the /DV parameter can be used:

Invisibility Parameters

Because OpenInsight applications rely upon OINSIGHT.exe, a visible window and icon for this program will appear in addition to those generated by the application itself. For runtime applications this can be a problem. First, it gives end users a way to close their entire application with potentially undesirable results. Second, many developers prefer to hide the underlying technology if they deploy commercial products.

The invisibility parameters provide a way to explicitly hide or show the OpenInsight and OpenEngine windows and icons:

NOTE: Runtime engines hide OpenEngine by default so the /HE parameter is unnecessary unless you want to show it.

Server Parameter

When OpenInsight is launched it loads OpenEngine by default using a randomly Named Pipe connection:

However, there are times when OpenInsight needs to connect to an already running engine (locally or remotely) or OpenInsight needs to create its own engine using a specific Named Pipe or TCP/IP port. Using the /SN parameter can accomplish either requirement:

System Monitor Parameters

/SM (System Monitor) and /NS (No Spy) are probably two of the least known and least documented command line parameters. These have no effect with runtime class engines:

Special Display Parameters

As of OpenInsight v8.0.2, two new parameters were added to provide special display options. The /CA parameter will update the caption that is displayed in the OpenInsight Application Manager to make it easier to identify different copies of OpenInsight that might be running on the same system. For instance, this can be helpful when primary and backup copies of the same application are running simultaneously. Often this can be confusing and changes can be made to the wrong copy:

NOTE: The caption must be a single word (i.e. no spaces). All captions will be uppercased when displayed in the Application Manager.

If no special logon banner is identified for a specific application, OpenInsight displays the OILOGON.bmp graphic file as the default splash screen. When the Application Properties dialog is used to specify a different logon banner, the OINSIGHT.ini file is updated accordingly:

[Application Manager]
.
.
Application=EXAMPLES
Login User=EXAMPLES
LogonBanner_EXAMPLES=.\bmps\sbi_logo.bmp
.
.

This method, however, is problematic since only the workstation that was used to update the logon banner will have a properly updated OINSIGHT.ini file. Other workstations will continue to display the OILOGON.bmp graphic file. One way to work around this is to modify the OILOGON.bmp with the desired graphical content and ignore the logon banner setting altogether.

A problem with this workaround is that multiple applications will be forced to display the same logon banner. Additionally, regardless of how the logon banner is identified, the image is only displayed long enough for OpenInsight to load in the memory of the workstation. Thus, fast machines only display these splash screens for a split second. This could be counter-productive if the image displays important information.

To resolve these issues, developers have resorted to alternative means of displaying splash screens (see SRP Application Launcher). However, these methods do not prevent OpenInsight from displaying a default logon banner. Previously, the best solution for this was to update the OILOGON.bmp graphic file to be a 1x1 black or white pixel. While better than nothing, discerning eyes can still detect this when OpenInsight is launched.

The /BN parameter now allows OpenInsight to avoid displaying its own logon banner:

OENGINE.exe Options

Occasionally OENGINE.exe will be launched independently. However, without the aid of special parameters, OpenEngine will only login to the SYSPROG database will not connect via any named pipes or TCP/IP ports that other systems can communicate with.

Server Parameter

As mentioned under OINSIGHT.exe Options, the /SN parameter can be used to force OpenInsight to connect to an already running engine. In order to launch a stand-alone OpenEngine using a specific named pipe or TCP/IP port, the /SN parameter is also used with the same syntax:

Database Parameter

In order to cause OpenEngine to login to a database other than SYSPROG, the database parameter needs to be used. This will allow the default tables for this database to be available when external systems connect in (although external connections will still need to provide proper user credentials):

Indexer Parameter

OpenEngine can be used as a dedicated indexer. Of course, the Database Parameter must also be used in order to have the correct indexed tables attached. It should be noted that the engine cannot be managed after it has been launched nor can it shut itself down (which might be necessary for scheduled backups). If tighter control is needed, OpenInsight can be launched with the Set_IDXSvr and Set_Bgnd_IX_Time commands to manage the indexing process.

Examples

OINSIGHT.EXE /AP=GL /UN=JACK /DV=1 /CA=LOCAL

Launch OpenInsight automatically into the GL application, with JACK as the user, and in development mode (if applicable.) If user JACK has a password then the default login dialog will appear prompting for the password. The caption parameter is being used to display LOCAL in the title bar of the Application Manager.

OINSIGHT.EXE /AP=GL /UN=JACK /PW=AGENT4CTU /SN=1030

Launch OpenInsight automatically into the GL application, with JACK as the user, and with AGENT4CTU as the password. This will attempt to connect to an engine already running on TCP/IP port 1030. If no engine is already running on that port then OpenInsight will launch a new engine using that port number. Since the /DV parameter was omitted, OpenInsight will attempt to launch in runtime mode.

OINSIGHT.EXE /AP=EXAMPLES /HE=1 /SN=REPORTS /BN=0

Launch OpenInsight automatically into the EXAMPLES application while hiding OpenEngine. The login dialog will appear since no user was specified. This will attempt to connect to an engine already running on Named Pipe REPORTS. If no engine is already running on that Named Pipe then OpenInsight will launch a new engine using that name. No banner (e.g. splash screen) will be displayed by OpenInsight.

OINSIGHT.EXE /AP=EXAMPLES /SN=\\10.0.0.2:REPORTS

Launch OpenInsight automatically into the EXAMPLES application. This will attempt to connect to an engine already running on Named Pipe REPORTS and on the machine using IP 10.0.0.2. Connecting to remote engines always requires the machine identifier (URL or IP) to precede the Named Pipe or TCP/IP port value. Otherwise, the local machine is assumed.

OENGINE.EXE PAYROLL /SN=ENGINE1

Launch OpenEngine automatically into the PAYROLL database using the Named Pipe ENGINE1.

OENGINE.EXE PAYROLL /I

Launch OpenEngine automatically into the PAYROLL database in dedicated indexer mode.

Custom Parameters

Only the official Revelation supplied parameters have been discussed thus far. Developers might want to support their own parameters. This can be a way of providing an interface for third-party systems:

OINSIGHT.EXE /AP=EXAMPLES /UN=USER /CUSTOMPARAM1=TEST1 /CUSTOMPARAM2=TEST2

This is where the GetCommandLine Windows API function comes in. The GetCommandLine command can be called anytime but it is most likely to be used during the CREATE event of the application’s entry point. A typical call might look like this:

CommandLine = GetCommandLine() ; // The entire command line is returned.
GoSub Parse_CommandLine ; // e.g. E:\FW\OINSIGHT.EXE /AP=EXAMPLES /UN=USER /CUSTOMPARAM1=TEST1

OpenInsight does not prototype this command automatically so this will have to be added by the developer. This can be done by either modifying the existing DLL_KERNEL32 record in the SYSPROCS table or by creating a new prototype record (e.g. DLL_KERNEL32_FOO). The latter method is recommended since changes to DLL_KERNEL32 can be replaced when OpenInsight is upgraded. Here is what the prototype definition should look like:

KERNEL32 
LPASTR STDCALL GetCommandLineA(VOID) as GetCommandLine

Note that the command itself can be named anything the developer prefers. Similar to the prototype record, this will help prevent accidental replacement of the function. To do this, simply change GetCommandLine to foo_GetCommandLine (or any naming scheme you prefer) in the prototype record.

Once the prototype record has been created, the Declare_FCNS command needs to be used to create a callable function. This should be done from the SYSPROG application using the System Monitor:

RUN DECLARE_FCNS 'DLL_KERNEL32'

SRP Application Launcher

While command line parameters offer significant control and flexibility in the way OpenInsight applications are launched, they also provide curious end users with information that might encourage them to experiment in different ways of accessing the system. This is one of the reasons why the SRP Application Launcher was developed. Here is a highlight of some of the features that this utility provides:

• An executable named anything the developer desires (e.g. myapp.exe).
• Separate INI file where the real command line information is kept.
• Display of a splash screen for any length of time.

The SRP Application Launcher provides distributable commercial or vertical applications a more professional appearance. Additionally, it is much easier to create shortcuts on workstations in a multi-user environment. All too often shortcuts are created with the wrong command line parameters or the default OINSIGHT.exe icon has not been changed. Consequently, the shortcut doesn’t work and/or look as expected. By having a custom named executable with an embedded icon, shortcuts are now simply a matter of pointing to the correct file:

More features and information can be read from the SRP Application Launcher Product Description page. An evaluation version of the product is also available for download.

Conclusion

We hope this white paper has provided you with helpful information on how to launch OpenInsight and OpenEngine. We are available for any questions you may have and, of course, you can always post questions on the available SRP Forum.