Starting the Framework

This document offers information about how the mBS framework is started on supported virtual machines.

Contents:

Starting the Framework

After you have successfully installed the Framework Professional Edition Package of the ProSyst mBS, you can start it in three ways:

By Using the Start Menu

Go to the start menu, locate the folder created by the installation of the mBS package and click Framework.

By Using a Shell Script

To start the mBS framework by executing a shell script file:

From the Command Line

To start the mBS framework from the command line:

Usage:

<command> [options] com.prosyst.mbs.impl.framework.Start

where:

When launching the framework from the command line, to avoid too many characters on the command line you may specify the location of a properties' file holding system properties for tuning the startup process of the framework. This is done through the mbs.prs.name system property, which specifies the name of the properties' file.

For example if using JDK:

Windows: java -Dmbs.prs.name=c:/init/mbserver/myproperties.prs com.prosyst.mbs.impl.framework.Start
Linux: java -Dmbs.prs.name=/home/user/init/mbserver/myproperties.prs com.prosyst.mbs.impl.framework.Start

In this file you may designate:

Initially, the mBS framework loads its system properties from the default.prs file located in the current startup directory.

Tip: For more information about the system properties discussed above, refer to the "System Properties" document.

Short Description of the Startup Process

When the framework is started, it performs the operations:

Starting the Standard Version

To start the Standard Version of the framework, use the server shell script available in each bin/vms/<vm_name> directory. The framework's Standard Version is set to read system properties from a properties file, called default.prs, located in the same directory.

Starting the Connector Version

To start the Connector Version of the framework, use the "conn" suffixed shell script available in each bin/vms/<vm_name> directory. The framework's Connector Version is set to read system properties from a properties file, called defaultconn.prs, located in the same directory.

Starting the Framework on Different VMs

Generally, to launch the mBS framework, it is necessary to have JVM-specific serverXxx.jar from the lib directory. The script files used to start the mBS framework on different VMs are located in the bin/vms directory. You can modify these files to fit the specific configurations of the target systems.

JDK

The server script in bin/vms/jdk starts the Standard Version of framework on the JDK JVM, and the serverconn one in the same directory starts the Connector Version. By default, the script is configured to load the serverjvm13.jar dedicated to JVMs compliant to JDK 1.3.x and 1.4.x.

For JDK 1.2.x, invoke the script with the "jdk1.2" parameter.

Supported options: Both scripts support options for launching the framework with security, lazy initialization, measurements, error log, empty storage and enabled framework extensions. For JDK, the Framework Loader is activated by default. In addition, JDK scripts support options for debugging the framework and installed bundles with a JDWP debugger and for profiling the framework and installed bundles with the ProSyst profiler.

J9

The J9 Virtual Machine was developed by IBM. It continually undergoes industry standard tests, such as the Modena JT++ and Plum Hall JVS test suites, to ensure its conformance to the Java industry standards. The IBM J9 virtual machine is included in WebSphere Studio Device Developer (WSDD) package. WSDD J9 virtual machine for embedded environments reduces memory requirements. You can download the WebSphere Studio Device Developer from http://www.ibm.com/embedded.

Configuring the Environment

All shell scripts related to running the mBS framework on J9 and for converting JAR files into JXE format require that you set the environment variable IVEHOME. IVEHOME should point to the home directory of the J9 JVM (e.g. for J9 2.2 this is the ive directory of the J9 installation package). The IVEHOME variable can be set (directory is arbitrary) as follows:

Windows: SET IVEHOME=c:/IBM/wsdd/wsdd4.0/ive
Linux: export IVEHOME=/IBM/wsdd/wsdd4.0/ive

Generating the Framework JXE File

The gensrv script in bin/vms/j9 generates:

The gensrv script has the following syntax:

gensrv [rm|max|gwp|foun|23]

where foun, max, gwp and rm represent the target J9 2.2 class library - jclFoundation10, jclMax, jclGwp and jclRM, respectively; and 23 stands for J9 2.3. For J9 2.2 resulting bundle JXE files are placed in the jxe22 directory, and those for J9 2.3 - in the jxe23 one. For both versions, the generated framework JXE file is saved to the lib directory.

By default, gensrv creates framework and bundle JXE files for J9 2.2 jclFoundation.

J9 Version Framework JXE J9 Class Library gensrv Command Options File
J9 2.2 server22.jxe jclFoundation10 gensrv jxembsFound10wsdd5.7.opt
servrm22.jxe jclRM gensrv rm jxembsRMwsdd5.7.opt
servgwp22.jxe jclGwp gensrv gwp jxembsGWPwsdd5.7.opt
servmax22.jxe jclMax gensrv max jxembsMaxwsdd5.7.opt
J9 2.3 server23.jxe - gensrv 23 -

Note that there are ready-to-use server22.jxe and server23.jxe and bundle JXE files in the Framework Professional Edition Package distribution.

Converting a JAR into a JXE

The jar2jxe script converts the specified bundle JAR into a JXE file for J9 2.2.

Tip: J9 2.3 contains its own jar2jxe.exe tool - use it instead of the jar2jxe script included in mBS.

The JXEs produced by the script are compatible with J9 2.2 and are placed in the jxe22 installation directory of the Framework Professional Edition Package.

Running the Framework on J9

The server script in bin/vms/j9 runs the Standard Version of the framework on J9 Virtual Machine. J9 VM should be installed on the machine running the framework.

You can launch the framework on the jclFoundation (default), jclRM, jclGwp and jclMax. You should call server from a command prompt in one of the following ways:

The serverconn script starts the Connector Version of the framework. You can run this version of the framework on the class libraries as with server. The Connector Version of the framework can be run only by calling its JAR (serverj9conn.jar) - JXE is not supported. Still, serverconn supports the common options of server.

Troubleshooting:

Running the Framework on PocketPC/J9

To launch the framework on a PocketPC running a J9 JVM, from the bin/vms/j9 mBS installation directory use the following link files on the target platform:

By default, the link files are configured to look for the J9 executable in the \j9 root directory. The startup system properties are defined in the jarce.prs file for the Standard Version of the framework and in the jarconnce.jar file for the Connector Version of the framework.

CVM

The CVM Virtual Machine was developed by Sun Microsystems specially for the J2ME TM technology. CVM extends the Java functionality towards embedded devices and supports Java 2. You can access Sun's CDC resources' page at http://java.sun.com/products/cdc/.

The server and serverconn script files in bin/vms/cvm start the framework on the CDC/Foundation profile of CVM on Linux OS. To run the framework by using the scripts, define an environment variable CVM_HOME containing the path to the CVM home directory.

export CVM_HOME=/usr/java/cvm

Supported options: Both scripts support options for launching the framework with security, lazy initialization, measurements, error log, empty storage, enabled framework extensions and Framework Loader.

CEE-J

The CEE-J JVM from Skelmir is a small footprint Java virtual machine compliant with JDK1.1.8. It also has support for JNI and AWT. Information about the technical features of the Skelmir VM is available at http://www.skelmir.com/products/ceej.html.

The server and serverconn scripts in bin/vms/skelmir start the framework on the CEE-J JVM. You should add a path to the CEE-J home directory to your system path:

Windows: SET PATH=C:\cee-j;%PATH%
Linux: export PATH=/usr/java/cee_j:$PATH

Supported options: Both server and serverconn support options for launching the framework with lazy initialization, measurements, error log, empty storage, enabled framework extensions and Framework Loader.

Starting the mBS Framework with Security

The framework of the ProSyst mBS can work with security on. It implements both Java 2 security model which are specified through the mbs.security property. Beside the security model, you have to turn on the ProSyst Security Manager by setting mbs.sm or mbs.resman.enabled system property to true.

Security Implementation

When started with security turned on, the Security Manager of the framework uses the Security module for security-related operations. The default implementation of the Security module uses the Java 2 security model an utilities.

Only certain JVMs support the Java 2 security paradigm, and hence the mBS framework can be launched with enabled security only on them unless a custom Security module is implemented. For such JVMs the mbs.security system property should be set to jdk12. The following list shows the availability of Java 2 security model for the JVMs which the mBS framework supports:

Policy File

The framework will not start if you do not point to a policy file with the permissions for access to the framework. The file is passed through the java.security.policy system property. It is recommended that you use the policy.all file from the bin/vms/<vm_name> directory of the Framework Professional Edition Package. java.security.policy should be specified in the starting script of the framework complying with the system properties' syntax of the used JVM.

Using the security Option

For the JVMs that support security (see the preceding table), the framework starting scripts (server or serverconn from bin/vms/<vm_name>) accept the security option, which will automatically turn security on in the framework. Open a command prompt in the JVM-specific startup directory of the framework and type:

server security

or

serverconn security

JVMs for which the starting scripts support the security option: JDK, J9, CVM and Perc.

Starting the Framework in Lazy Mode

You can conveniently launch the framework with enabled lazy initialization by providing the "lazy" option to the framework starting script, i.e. to server or to serverconn from the bin/vms/<vm_name> directory. Open a command prompt in the JVM-specific startup directory of the framework and type:

server lazy

or

serverconn lazy

JVMs for which the starting scripts support the lazy option: All except for Tao.

Starting the Framework with Measurements

You can start the framework with default measurements turned on by using the "measurements" option to the starting script (server or serverconn from bin/vms/<vm_name>). Open a command prompt in the JVM-specific startup directory of the framework and type:

server measurements

or

serverconn measurements

JVMs for which the starting scripts support the measurements option: All except for Tao.

Starting the Framework with Framework Loader

You can conveniently launch the framework with active Framework Loader directly by using the fwloader option to the JVM-specific server or serverconn script.

server fwloader

or

serverconn fwloader

JVMs for which the starting scripts support the fwloader option: All except for Tao.

Starting the Framework with Errors Logged

You can conveniently launch the framework with active error log directly by using the fwerr option to the JVM-specific server or serverconn script.

server fwerr

or

serverconn fwerr

JVMs for which the starting scripts support the fwerr option: All but the Tao JVM.

Starting the Framework with Enabled Framework Extensions

You can start the framework with active support for framework extension bundles by using the fwext option to the JVM-specific server or serverconn script.

server fwext

or

serverconn fwext

JVMs for which the starting scripts support the fwext option: All but the Tao JVM.

Starting the Framework with Clean Storage

You can start the framework with empty storage so that the initial set of bundles installed at startup is determined by the Boot module, i.e. from a boot INI file. Use the clean option to the JVM-specific server or serverconn script.

server clean

or

serverconn clean

JVMs for which the starting scripts support the clean option: All but the Tao JVM.

Starting the Framework for JDWP Debugging

You can start the framework for remote debugging over the Java Debug Wire Protocol (JDWP). Use one of the following options to the JVM-specific server or serverconn script:

JVMs for which the starting scripts support the jdwp/jdwp_suspend option: All but the Tao JVM and the PJEE JVM.

Starting the Framework for Profiling

You can start the framework for remote profiling over the ProSyst JProfiler. To be able to profile the performance of the mBS framework and the bundles running within its context, you need the JProfiler agent shared library (prof.dll for Windows or libprofl.so for Linux), included in the JProfiler installation. The library should be available in the system path, the PATH environment variable on Windows or the LD_LIBRARY_PATH environment variable on Linux should contain a path to the library's parent directory.

Use one of the following options to the JVM-specific server or serverconn script to launch the mBS framework with enabled profiling:

JVMs for which the starting scripts support the profiler/profiler_attach option: All but the Tao JVM.

References

Getting Started