Expeditor Deployers: Updating the rcplauncher.properties file

This section describes how you can update one or more elements of a user's Lotus^® Expeditor Client platform by modifying the rcplauncher.properties file.

The rcplauncher.properties file is managed through install handlers. It contains properties that are required by the launcher for global actions.

Without correct values in this file the platform will not start. Any other properties in this file will be ignored. This file should not be modified except through install handlers.

File locations:

${rcp.home}/rcp/rcplauncher.exe
${rcp.home}/rcp/rcplauncher.properties

A typical rcplauncher.properties file looks like this:

rcp.install.id=1156180825640

The branding properties (product and osgi.splashPath) are managed from the rcplauncher.properties.

osgi.splashPath=platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personali
ty.branding,platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personality.b
randing.nl1,platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personality.b
randing.nl2,platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personality.b
randing.nl3 
product=com.ibm.rcp.platform.personality.branding.DefaultProduct

The calculation used to locate the user's workspace is externalized in this file.

rcp.data=$(env.APPDATA)/Lotus/XPD

This value can be customized in the installer.

The rcp.install.id property is a unique number generated by the installer. It is used to assure there are no collisions between multiple installs of the platform. This is copied to the user’s new rcpinstall.properties file.

provisioning.manifest=file\:/${rcp.home}/rcp/deploy/install.xml

The definition of the base install chosen by the administrator is defined in this file. When a new user starts the platform for the first time the configuration is provisioned to this level.

provisioning.manifest.version=1156180825640

This is the version of the provisioning.manifest file being used. The number usually starts with the current rcp.install.id. When a user starts the platform and the launcher determines that the manifest version is not identical to the level in the user’s rcpinstall.properties a provisioning cycle will be initiated. The level actually provisioned for a user is written to the user’s rcpinstall.properties file by the provisioning component.

install.configuration=user

This is set by the original install and should never be changed. This is copied to the new user’s rcpinstall.properties file.

update.policy.managed=true

This is an internal property and should not be changed. It may be ignored in future versions of rcplauncher.

rcp.base.location=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.1.0.0-20060817

This property points to the base plugin that contains:

base rcpinstall.properties file – Initial values represent what is in the core set of features. All changes above this level are caused by the running of install handlers.
startup.jar, eclipse.exe, and launcher.jar located and executed from this location.
rcplauncher.exe is located here but is copied to <install dir>/rcp/rcplauncher.exe by the plugin install handler.
Platform.xml and config.ini are here and are used to seed the initial configuration directory.

This property is copied to a new user’s rcpinstall.properties file. From that point forward, it is allowed to get out of sync with the rcplauncher.properties value. That would happen if a user chooses to run with a different version.

provisioning.application=com.ibm.rcp.provisioning.application.ProvisioningApplication

This is an internal property and should not be changed.

jvm.location=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.jcl.desktop.win32.x86_
6.1.0.0-20060812/jre/bin/j9w.exe

This points to the Virtual Machine (VM) that implements the Java™ specifications that should be used by new users. When creating a user’s initial configuration, this property becomes the vm property in the user’s rcpinstall.properties. This property and the vm property are managed by feature install handlers. From that point forward, the user is allowed to choose a different VM version or possibly even a different VM. The vm property would be managed by an install handler.

jvm.feature.id=com.ibm.rcp.jcl.desktop.win32.x86.feature 
jvm.feature.version=6.1.0.0-20060812
jvm.parent.feature.id=com.ibm.rcp.jvm.feature
jvm.parent.feature.version=1.0.0.0-20060930

These are internal properties and are managed by install handlers. They are used for correcting the initial platform.xml.

Windows^® has a 256-byte limit on command length that can be stored in the properties for an icon. If you are customizing launch icons to contain personalities or Dcomamnds, for example, this limit can be easily exceeded. As a work-around, you can define the arguments as properties in the rcplauncher.properties file. The launch command will only have to contain the following:

rcplauncher.exe –config launchconfigone

rcplauncher.exe –config launchconfigtwo

When the launcher notices the -config launchconfigone arguments, it substitutes the properties stored in the rcplauncher.properties file as if they had been included on the command line.

For example, if the actual command should be rcplauncher –console -application com.ibm.MyApplication -nl de –path “path with spaces and {DBCS}” –vmargs -Dmyproperty=test, the following properties would be stored in rcplauncher.properties:

config.launchconfigone.1 = console
config.launchconfigone.2 = application
config.launchconfigone.3 = com.ibm.MyApplication
config.launchconfigone.4 = nl

config.launchconfigone.5 = de
config.launchconfigone.6 = -path
config.launchconfigone.7 = path with spaces and \uxxxx\uxxxx… 
config.launchconfigone.8 = -vmargs 
config.launchconfigone.9 = -Dmyproperty=test

Where a space would exist between elements on a full command line, the elements would be represented as separate config arguments. In the example above, the elements -nl de are separated by a space on the command line, so would become separate config arguments.

Notes^®:

The property file does not ensure that these arguments will stay in order. The numbering scheme assures that the arguments can be restored correctly. The number must start with 1 and be numbered consecutively.
The path must be entered on the command line surrounded with quotation marks. Not only is that not required to be in the file, it is not allowed. Quotation marks can be added if they are part of the arguments but do not add additional quotes.
The path can contain non-ASCII or non-ISO8859-1 characters. Any non-ASCII characters must be escaped with \uxxxx. You can generate these values with a Unicode 16 editor and converting with the Java program native2ascii.
The vmargs must be entered in the rcpinstall.properties as vmarg.xarg=-Xarg. However, for this file, enter the properties only as described above. The value is always exactly as would be contained on the command line – except as noted.
Using the –config argument does not restrict adding additional arguments on the actual command line. The launcher does not guarantee the order of combining the properties and the command line arguments (except for the overrides noted below). The launcher will maintain the order of the specified properties from the file.

Some of the arguments that can be entered on the command line or in the config.xxx properties have an override priority. The VM, application, product, personality, and plugincustomization properties have the following override priority:

Command line
config.xxx property
Property in rcpinstall.properties

The workspace has the following priority:

–data on the command line
–data in the config.xxx property
rcp.data property in the rcplauncher.properties

The locale has the following priority:

–nl on the command line
–nl in the config.xxxx property
com.ibm.rcp.core.locale in rcpinstall.properties. This is normally set from a preference page and will replace the value set by Priority 4
com.ibm.rcp.core.locale in rcplauncher.properties. This is normally set by the installer and will populate the default language for a user’s rcpinstall.properties file.
The locale calculated by the platform

The BIDI value has the following priority:

–dir on the command line
–dir in the config.xxx property
com.ibm.rcp.core.bidi in rcpinstall.properties. This is normally set from a preference page.
Directory calculated by the platform when –nl is specified

Note that this file may be populated with config properties from an install handler.

The installer creates and populates the rcplauncher.properties file. Users should not make changes to this file. Only ISVs and developers should make changes to the file; however, they should not change the installed values. Administrators can add config properties.

For information on how to manage this file, see the following sections:

Managing using the Device Manager server: Managing properties files

Managing Rich Clients using the Portal server: Managing properties

Managing using another management system: Managing properties

To enable the flexibility to change the drive that IBM^® Lotus Expeditor is launched from, the rcpinstall.properties should not contain absolute path references to files or directories in the install directory.

Rather than specifying the absolute location of the install directory, the string ${rcp.home} is used to reference the install directory, and ${rcp.data} is used to refer to the workspace directory. Upon launch, the launcher will replace the value of these tokens with the correct location of the IBM Lotus Expeditor install directory and workspace directory prior to passing the arguments to the Java executable for IBM Lotus Expeditor.

When adding new properties to rcpinstall.properties, or making changes to existing properties, it is important that ${rcp.home} or ${rcp.data} is used when referring to the install or workspace directories, and to not use any absolute path references.

The rcp.data property is written by the installer at install time and should not be modified. The rcp.data property gives a versatile way to specify where the workspace is to be located. See Installing the Lotus Expeditor Client for shared launching from a network drive for information on how to specify this value before installing. This value will be copied to each user’s rcpinstall.properties and will override the default algorithm for calculating the workspace location.

The default value for rcp.data for IBM Lotus Expeditor is rcp.data=${env.APPDATA}/Lotus/XPD

If you are upgrading from IBM Lotus Expeditor 6.1, the default rcp.data will keep the original algorithm. For Windows, it appears as:

rcp.data=${env.HOMEDRIVE}${env.HOMEPATH}/IBM/RCP/${prop.rcp.install.id}/${env.USERNAME}/

The placeholder ${env.”system environmental variable”} is used to specify the use of a system environmental variable.

The placeholder ${prop.”rcplauncher_property”} is used to specify the use of a property from rcplauncher.properties.

The installer can also write the following properties to the rcplauncher.properties:

com.ibm.rcp.core.locale
com.ibm.rcp.core.bidi

For more information on these properties, see Updating the rcpinstall.properties file. These properties allow the installer to specify a default language for each user other than English. These will be copied to each user’s rcpinstall.properties when their configuration is created.