Command Line Options

Quick Reference (Command line options)

• -NoSplash [Open without splash screen]

• !Minimize [Open in the as configured minimized state]

• DEFERSKIPMSG [If this is found in the command line, it only affects the second instance - the default actions will occur, but no message (no dialog/MessageBox) will be shown (see below for notes/details)]

• DEFERNOACTION [If this is found in the command line, it only affects the second instance - nothing will occur when the EXE is launched - the second EXE will just close itself (see below for notes/details)]

• /k=mynew.kbf [Override KeyBoard File (must be in Config Path location)]

• /i=mynew.ini [Override Initialization File (must be in Config Path location)]

• x=123[%] [Override opening x screen position, add % to use screen percentages (calculated)]

• y=321[%] [Override opening y screen position, add % to use screen percentages (calculated)]

Prior to Version 1.76, the only command line option was the ability to specify the NoSplash setting - see NoSplash in the Iniitialization file description. [Path]\ONSCREEN.EXE -NoSplash In the implementation, the - (dash) is actually the trigger, and the notes specify NoSplash only as a description so maintainers can understand what the command line means - it is not required, and in fact, can be anything as long as there is a - (dash).

In the 1.79 release, a command line based "Open in the minimized state" has been added. Prior to this, the shortcut link properties needed to be modified to indicate the "Run:" state as Minimized (instead of Normal Window (or Maximized)). This is implemented similar to the -NoSplash and can be used as !Minimize or Minimized! - the exclamation point character is the trigger, and if it is present, the internal operation will match the Show Window properties from the shortcut link. It is recommended you include the text of Minimize or Minimized for future maintainers.

In the 1.76 release, in addition to the -NoSplash code, there is support for a /k=[file] and/or a /i=[file]. These provide an override to the default KEYBOARD.KBF (/k) and ONSCREEN.INI (/i).

There should be no spaces in the command line entry, except to separate multiple entries.

(e.g. C:\Program Files\ONSCREEN\ONSCREEN.EXE /k=mykbf.kbf /i=mykbf.ini -NoSplash)

The [file] specified must reside in the current configuration folder, as specified by the ConfigPath setting in the Initialization File (except in Terminal Server version).

The code checks for both upper & lowercase k (K) and i (I). The trigger is the = (equal) sign, and the code looks to the previous character for the k or i, and the following characters up until a space or end of line for the [file].

The /k option updates the KEYBOARD.KBF file with the specified [file]. There is no error checking to guarantee the file exists, or that it is a valid KBF file, so care should be used when implementing these options. The [file] specified with the /k option MUST be a copy of a previously saved configuration (i.e. copy KEYBOARD.KBF to MYKBF.KBF). A Build-A-Board 2.10 generated KBF file may also be used.

The /i option references the given [file] for configuration information, instead of the default ONSCREEN.INI, allowing different settings to be used.

The implementation of the 2 options is internally different (because of internal design). The /k option for OnScreen actually copies the specified [file] to KEYBOARD.KBF, then continues on as normal. The /i option internally references the specified [file], leaving the default ONSCREEN.INI file intact.

In order to ensure proper operation, certain settings (panels, colors, etc.) are written to the INI file when the /k option is used. This is done to ensure a match between the layout information, and the details in the INI file. When the /k override in the command line is used, the following occurs:

• The specified [file] is copied to KEYBOARD.KBF

• If only the /k option is used, overlapping features from the specified configuration [file] are written to the ONSCREEN.INI.

• if both /k and /i options are used, the INI settings will be used. Therefore, a "matched" pair should be used whenever both options are specified.

• If the /k is used, any other "launch" should probably also require the /k option to ensure the desired layout appears.

A "matched" pair means saving both Settings and Position, then closing OnScreen. Copy the KEYBOARD.KBF to MYNEW.CFG, and ONSCREEN.INI To MYNEW.INI.

In the 1.77 release, an X/Y coordinate can also be used, e.g X:200 Y:300 (e.g. C:\Program Files\ONSCREEN\ONSCREEN.EXE -NoSplash x:200 y:300)

The implementation looks for either the : (colon) character, or the = (equal sign), and looks at both upper or lower case x (X), y (Y). So X=200 and Y=300 will also be recognized. Negative numbers can be used. There should be no spaces in the command line except to separate options.

In the 1.78 Release 2, a percent sign character can be used to position the X/Y coordinates based on the relative position specified (percent of total screen resolution), rather than a fixed location, e.g. x:34% y:70%.

The implementation requires the % character to immediately follow the numeric value. Valid values for X/Y must be in the range 0-100 - negative numbers or numbers over a 100 will revert to acceptable values. The calculation includes the size of the keyboard window, and will keep the entire window visible, so it is a dynamic calculation based on the specified percent, the screen resolution, and the current size of the window. Some examples: [C:\Program Files\ONSCREEN\ONSCREEN.EXE x:20% y:75%], or [C:\Program Files\ONSCREEN\ONSCREEN.EXE -NoSplash x=75% y=50%].

Troubleshooting / Diagnosing Startup

In the 1.78 Release 2, "STARTDEBUG" can be used as the command line to display to the screen key code points during the initialization of the software. During the program startup, there is a direct to display "Reached Code Marker ID" code indication. As the code progress and reaches key points in the startup sequence, a code marker (e.g. 1003) is reached, and using a direct to display debugging feature, the code marker is directly displayed on the left side of the system display. If there is an error or other problem starting, the last code marker display will help indicate where the code stopped, and what it was doing.

The following is the list of the codes and what has happened up to that point:

• 1001 In WinMain code, no system calls made yet

• 1002 After check for Window already existing (Previous Instance)

• 1003 After Class Registered with system (Register Class) Pre Window Creation

• 1004 After Window created

• 1005 Free System Timer verified, internal variables initialized

• 1006 DLL's attached

• 1007 Macro file verified / loaded, Read from INI

• 1008 If Win Logon, IMGSERV.EXE launched (95/98/Me) - post launch (Code after OpenFirst=1 drop-out)

• 1009 Several system calls completed

• 1010 After Keyboard Layout read in / prepare for paint

• 1011 System Timer set - last spot before paint

• 1012 After paint, pre System hooks (95/98/M3/NT)

• 1013 After System hooks set (95/98/M3/NT)

• 1014 Final call to DLL's, last spot before message loop

• 1015 After message loop, before all internal cleanup

There are also several "critical error" spots that can be tested easily (refer to ConfigPath setting to ensure you are working with correct file location!)

1) Rename MAC00000.KMF to something else (KM, BAK, etc.)

Run OnScreen - it will stop after 1006 and return false in WinMain

2) Rename ONSCREEN.INI to something else (IN, HLD, etc.)

Run OnScreen - it will stop after 1006 and return false in WinMain

3) Rename KEYBOARD.KBF to something else (KB, HLD, etc.)

Run OnScreen - it will stop after 1009 and return false in WinMain

As a separate reference, these details were asked by a customer doing custom integration work, and the following is a generalized flow of the startup & important events when the executable is started.

• Opening Check - should MTSOPEN.EXE be run (reference OpenFirst settings in INI file)

• Verify MYTLIB.DLL (Existence, LoadLibrary)

• Register Window Class (RegisterClassEx)

• Create Windows (CreateWindowEx)

• Verify System Timer Available

• Initialize variables, global memory, files, etc.

• Interface Libraries (LoadLibrary)

• INI File

• Keyboard Configuration file

• Show/Update window (splash window - see Note below)

• Message Loop