SysConsole/SysWindow: Saving Configuration

The .def Configuration File

The SysConsole and SysWindow automatically maintain a user preference file with stored configuration information. Once started, the SysConsole or SysWindow scans the configuration file to find and restore the user's preferred colors, font, font style and point size, number of columns and rows, and other user-configurable settings. When modified, BBj writes these settings to the configuration file and stores them until needed for the next session.

Although a SysConsole or SysWindow only deals with a single configuration file at a time, it is possible to have many such files to choose from when starting BBj. Configuration files with the extension .def reside in the special directory BBjSysWinConfig/ located at <bbjhome>/cfg/. The cfg/ directory contains such files as BBj.properties, BBjServices.out, and BBjServices.err. The default configuration file is BBjSysWindowDefault.def, which provides the configuration information if the user does not specify a .def file on the BBj command line. If the user specifies a .def file that does not yet exist, BBj obtains configuration information from the default .def file. As of BBj 2.0, SysWindow configuration files are stored on the server rather than user's client machines. This enables developers and system administrators to ensure the availability of a common configuration to all users, since all the configuration files are in a central location and protected from unauthorized changes.

A SysConsole or SysWindow that appears inside a BBj MDI (Multiple Document Interface) window stores its configuration information in files with the extension .def_MDI. The configuration data of SysWindows displayed inside a BBj MDI is incompatible with that of regular SysWindows, because the MDI window resizes and repositions its SysWindow in ways not possible or desirable for a stand-alone SysWindow. Two separate types of configuration files, .def and .def_MDI, prevent the SysWindow configuration settings from affecting the settings meant for MDI SysWindows and vice versa.

The .def file is a simple text file containing a single set of SysWindow configuration parameters that the developer can manually edit using any text editor. The SysWindow performs validation checks on the information obtained from the .def file, replacing any invalid data entered during a manual editing session with default values. If there is no .def file in the BBjSysWinConfig directory, the SysWindow creates a new BBjSysWindowDefault.def file (or BBjSysWindowDefault.def_MDI if the SysWindow is inside an MDI frame) and uses the default value for each parameter.

In the typical .def file presented below, parameters with values between 0 and 255 represent individual dim and bright colors. Configuration parameters representing on/off states of the SysWindow have the value 1 for 'on' or 0 for 'off'. The XLocation and YLocation parameters represent the number of pixels from the upper left corner of the screen to the upper left corner of the SysWindow frame. The SysWindow updates these values as the user moves it around on the display screen. Configuration parameters that begin with the word "Edit" apply to the graphical line edit dialog that is available from the SysConsole. The location, size, font, font point size, and font style used in the edit dialog are all stored in the .def file. The file header contains date and time information not used by the SysWindow, but could be useful to an administrator trying to determine the most frequently used .def files.

#BBj SysWindow configuration properties
#Fri Nov 14 11:42:47 MST 2003

InvertColors=1
EditWidth=500
Style=1
UseScrollBars=0
YLocation=173
EditStyle=1
DimGreen=0 128 0
DimBlue=0 0 128
DimYellow=128 128 0
Columns=80
DimMagenta=128 0 128
EditHeight=250
VaryFontSize=1
BrightGreen=0 255 0
BrightCyan=0 255 255
BrightMagenta=255 0 255
DimWhite=128 128 128
BrightBlue=0 0 255
LockWindow0=0
XLocation=290
EditFont=Monospaced
BrightBlack=0 0 0
DimRed=128 0 0
Font=Monospaced
LockColsAndRows=0
FileName=/home/users/BBj/cfg/BBjSysWinConfig/BBjSysWindowDefault.def
BrightRed=255 0 0
DimBlack=0 0 0
EditXLocation=17
MapRGBColors=0
DimCyan=0 128 128
Rows=25
UseEditDialog=1
EditPointSize=14
DimThreshold=128
EditYLocation=14
BrightYellow=255 255 0
PointSize=12
BrightWhite=255 255 255

User-specific Configuration Files

The BBjSysWinConfig/ directory may contain as many different configuration files as the user needs, with the restriction of only one BBjSysWindowDefault.def file. To create or specify configuration files other than the BBjSysWindowDefault.def file, use the -a (application name) and -n (user name) command line options. It is not necessary to put the name of an application after the -a or the user name after the -n.

For example, if a user starts a SysWindow-based application with John as the -a parameter and Doe as the -n parameter, they create a new configuration file named JOHNxDOE.def. The user's name, converted to capital letters and with an 'x' placed between the first and last names, identifies the file as a customized .def for John Doe. Using only the -a parameter produces a file called JOHN.def, and only a -n produces DOE.def. Moreover, a file named FOOTWEARxIMELDA.MARCOS.def would be the .def configuration file Imelda uses when she runs her "What pair of shoes shall I wear today?" database application.

It is increasingly common for developers to deploy and launch BBj applications via the Web using Java Web Start, which depends on a JNLP (Java Network Launching Protocol) configuration file. The JNLP file contains the command line parameters used to start BBj. Because many users depend on a single JNLP file containing a single set of BBj command line parameters when running BBj with Java Web Start, it is not possible to include user- or application-specific -n and -a parameters. As of BBj 4.0, it is possible to used an asterisk (*) character with the -a and -n parameters to cause the system to locate and use a unique .def configuration file based on the name of the application running and the user's login name. If the JNLP file contains -a* and/or -n* in the list of BBj command line parameters, each user of a Web Start BBj application works with his or her own unique .def file. As an example, when John Doe starts his company's accounting package, with -a* and -n* in the JNLP file, the name of the .def file is ACCMOD1.BBJxJOHND.def because the main program's name is Accmod1.bbj and the user's login name is johnd. Jane Smith, when running the same application with the same JNLP file, gets ACCMOD1xJANES.def for her configuration file.

Reloading Configuration Files During a BBj Session

As of BBj 4.0, users are no longer limited to using the configuration file that was loaded at the start of the session. The SysWindow Settings menu contains a new item called .DEF Configuration, which opens the dialog shown below:

The dialog reports the name and location on the server of the .def configuration file currently loaded in the SysWindow. Entering a new -a parameter and/or -n parameter and pressing the [OK] button loads the corresponding configuration file, changing the SysWindow to reflect the information stored in this new file. To test a configuration file, use the [Try] and [Restore] buttons. Enter new parameters, and press [Try] to load the new file, change the SysWindow, and keep the dialog open. [Restore] reloads the original configuration file and returns the SysWindow to its previous condition, leaving the dialog open for further testing. Press the [Cancel] button at any time to restore the configuration file, change the SysWindow back to its original configuration, and close the dialog.

Controlling Modifications to Configuration Files

To prevent a user from modifying .def files that customize their SysWindows, set the file access permissions granted by the operating system for the particular file. For example, a system administrator may write-protect the BBjSysWindowDefault.def file as a common baseline for all users while still allowing modification of an individual user's customized .def files.

To protect a file in Microsoft Windows, right-click on the .def file in Windows Explorer and then select [Properties] from the popup menu. In the new dialog, set the file to Read-only.

On a UNIX or Linux server, use the chmod command to set write permissions for the owner, group, and world as desired. Note that having 'root' access might be necessary in order to accomplish this. In most installations, 'root' runs BBjServices, which means that 'root' owns all .def configuration files. To prevent typical non-root users from modifying a .def file, grant read-only permissions to the group and the world:

chmod 644 BBjSysWindowDefault.def

To allow users to modify a given .def file, grant both read and write permissions to the owner, group or world as necessary:

chmod 666 SOMEAPPxSOMEUSER.def

The SysWindow first checks to see if the user on the client is the owner of the file and if the owner has write permission. If the user is not the owner of the file, the SysWindow then checks if the user is a member of the owner's group and if the group has write permission. If the user is not a member of the same group, SysWindow checks if the world has write permission. After each of these tests fail, the SysWindow abandons trying to write altered information to the .def file.

Examples

The following examples illustrate how the SysWindow configuration system works in different situations.

Case 1: A user starts a SysConsole or SysWindow session without specifying the -a or -n parameters.

The server attempts to obtain the client's configuration data from the default configuration file BBjSysWindowDefault.def (or BBjSysWindowDefault.def_MDI if running in an MDI frame). If the file does not exist, the SysWindow creates a configuration file with BBj hard-coded defaults. As soon as the user changes the configuration by changing a color or font or moving the window to a new position, the client forwards the altered configuration to the server, which attempts to save it to the default file.

If the default file is write-protected, then attempts to save the file fail (this means that the user loses any changes made to the SysWindow configuration settings during the session). If the default file is not write-protected, the new configuration overwrites the default file each time the user changes a setting (this means that the user saves all changes made to the SysWindow configuration settings during the session).

Case 2: A user starts a SysConsole or SysWindow session and specifies some combination of the -a or -n command line parameters.

The server attempts to find a matching configuration file name. If the server finds a match, it opens and forwards the file contents to the clients. The SysWindow uses only this configuration file and does not read or write the BBjSysWindowDefault.def (or BBjSysWindowDefault.def_MDI) file.

If no such file exists, the server reads values from the default file. When the user makes changes, a new file matching the -a and -n parameters will be created and used to hold the new configuration. In this way, users begin with the default configuration, yet have the ability to save their personal preferences without ruining the officially approved defaults.

Case 3: A user starts a SysConsole or SysWindow session via Java Web Start, where the JNLP file contains some combination of the -a* or -n* command line parameters.

The server substitutes the name of the running application for the asterisk (*) in the -a parameter, and the user's login name for the asterisk in the -n parameter. It then attempts to find a configuration file with a name that matches. Once found, the server opens the file and forwards its contents to the client. The SysWindow uses only this configuration file and does not read or write the BBjSysWindowDefault.def (or BBjSysWindowDefault.def_MDI) file.

If no such file exists, the server reads values from the default file instead. When the user makes changes, a new file matching the substituted -a and -n parameters is created and used to hold the new configuration. In this way, Web Start users can begin with the default configuration, yet have the ability to save their personal preferences without altering the officially approved defaults.