1.0 Launching the workbench
1.1 Advanced launching topics
1.2
Displaying the location of the workspace in title bar of the workbench
1.3 Using WebSphere Studio
Version 5.1 with Version 5.0 workspace
2.0 Known problems with the workbench
2.1 Manual refresh required when files modified outside the workbench
2.2 Problems on Windows: using OLE documents
2.2.1 Dirty state not tracked properly for OLE document
2.2.2 OLE document crashes can cause
WebSphereR Studio to exit suddenly
2.3 User interface not responding
2.4 Copying items from the
Tasks list
2.5 DBCS font issues
2.6 May encounter errors when you restore a perspective for a migrated
workspace
2.7 Minimum display resolution
2.8 External tools will automatically put path variables containing spaces in
quotation marks
2.9
Default text file encoding may be detected incorrectly (Windows XP/2000
only)
2.10
Updating the toolbar in multipage editors
2.11
Certain shortcut keys do not work with an Arabic keyboard layout
2.12 Must reset class path variables if you import preference
setting from another installation of WebSphere Studio
2.13 Simple project
creation should open the Resource perspective
2.14 Linked resources and multiple
output folders
2.15 Overwrite mode cannot be disabled for AbstractTextEditor and subclasses
2.16 Working with large projects and files
3.0 Known problems with editors
3.1 Markers are not properly removed
3.2
Default HTML and JSP editor does not support bidirectional languages
4.0 Running on Different VMs
4.1 Running on J9
5.0 Program errors caused by utc.dll
6.0 Ant
6.1
Preferred Output Level on External Tools preferences page has no effect for Ant
6.2 Ant UI in External Tools does not handle ENTITY entries in all cases
6.3
Xerces JARs no longer required on runtime Ant classpath
6.4 Custom Ant tasks and Ant types must be
separate from plug-in library JARs
6.5 Concurrent Ant builds not
supported
6.6 Running certain
Ant tasks cause memory leakage
6.7 Tasks that
require input lock up workspace
6.8 Ant Editor code
completion based on Ant 1.5
After installation, the workbench is started by running the executable program found in the top-level installation directory.
By default, the workbench creates a directory called workspace. This directory is used as the default content area for your projects as well as for holding any required metadata. For shared or multi-workspace installations you should explicitly state the location of your workspace rather than using the default. There are two ways to control the location of your workspace: using the current working directory or using the -data command line argument.
The easiest way of using the current working directory is to create a shortcut using the following steps:
Other options are to add the -data argument (for example, -data c:\myworkspace) to the Target line in the shortcut or to start the program from a command prompt and include the -data argument.
WebSphere Studio will fail to launch if installed in a directory whose path contains certain invalid characters, including :%#<>"!.
Eclipse (the platform that WebSphere Studio is built on) offers a number of execution options of interest to people developing or debugging plug-ins. The general form of running the executable is:
platform [platform options] [-vmargs [Java VM arguments]]
where platform is the name of the executable found in the top level directory of your installation directory and the valid platform options are:
| -application <app id> | Identifies the application to run. If not specified, the workbench is run. Applications are declared by plug-ins supplying extensions to the org.eclipse.core.runtime.applications extension point. |
| -boot <boot code path> | Defines the path to the boot plug-in code (that is, boot.jar). Only required when changing the relative location of startup.jar and boot.jar. |
| -consolelog | Mirrors the platform's error log to the console used to run the platform. |
| -data <workspace path> | Defines the path of the workspace on which to run the platform. |
| -debug [options file path] | Puts the platform in debug mode and loads the debug options in the specified file. If a file path is not given, the platform looks in the platform installation directory and in the workspace's metadata directory for a file called .options. |
| -dev [classpath entries] | Puts the platform in development mode. The optional class path entries (a comma-separated list) are added to each plug-in's class path. For example, when developing plug-ins, use -dev bin to add the JavaTM tooling's bin directory for each plug-in. Redundant or non-existent class path entries are eliminated. |
| -nosplash | Runs the platform without putting up the splash screen. |
| -os <os-id> | Defines the operating system on which the platform is running. Typically the platform can detect the OS but some situations may require explicit specification. The value specified here is related to Platform.getOS(). |
| -vm <vm path> | Specifies the Java VM to use to run the platform. If not specified, a Java VM is located relative to the executable. |
| -ws <ws-id> | Defines the window system on which the platform is running. In many cases the platform can detect the window system but some situations may require explicit specification. The value specified here is related to Platform.getWS(). |
All arguments following (but not including) the -vmargs entry are passed directly through to the indicated Java VM as virtual machine arguments (that is, before the class to run). All arguments preceding the -vmargs entry (with the exception of -vm and -nosplash) are passed directly to the platform for interpretation.
If you want the location of your workspace displayed in the title bar of the workbench, you must start WebSphere Studio using the following command:
WS_installdir\wasexpress.exe -showlocation -data c:\workspacewhere WS_installdir is the location you have installed WebSphere Studio and c:\workspace is the location of your workspace.
You can either start WebSphere Studio from a command prompt using this command or change your desktop shortcut.
When WebSphere Studio Version 5.1 is started for the first time using an existing WebSphere Studio Version 5.0 workspace a dialog box appears showing you one way to migrate from Version 5.0 to Version 5.1. Click OK to migrate the Version 5.0 workspace to Version 5.1, or click Cancel to stop WebSphere Studio from starting.
When the workspace is migrate to Version 5.1, you can still use the workspace with Version 5.0 as the metadata of the new project features of Version 5.1 are ignored and can be read by Version 5.0. You cannot make any changes in Version 5.0 to the projects in the workspace that would effect the metadata or overwrite the metadata of the new project feature of Version 5.1 projects.
For more information about the new project features in Version 5.1, refer to the WebSphere Studio Migration Guide.
The following are known problems with the workbench UI in this release.
When files within a project are added or removed outside of WebSphere Studio, or when an external editor is used to modify a file within a project, a manual refresh must be done in order for the changes to show up in the workbench. To do this, select the project in the Navigator view and click Refresh in its pop-up menu. This only refreshes the selected project. Click F5 to refresh all projects.
The following problems are known to occur when using OLE documents in the workbench (for example, editing a .doc file in Word or WordPad).
The dirty state for an OLE document is not updated properly. This causes the workbench to prompt you to save the contents of a document when it is closed, even if the contents have already been saved.
If an OLE document crashes, the workbench menus may become inconsistent or WebSphere Studio may exit suddenly.
The workbench user interface is composed of views and editors. The view or editor that has focus has its tab highlighted in blue. The highlighted user interface component has control, and, in the case of editors, determines the contribution that is made to the common workbench menu tree and action icon set. That is, when an editor is activated additional menu choices and action icons may appear on the workbench user interface. When working with a resource in an editor you may also interact with a view that supports the editor (such as the Outline view that supports the Java source editor). When the view has focus the menu choices and action icons associated with the editor may disappear. To bring these menu choices and action icons back, activate the editor.
There are multiple techniques you can use to activate the editor. The technique required may depend on the type of editor you are using.
To activate the editor you must click on either the title tab or an editable area of the editor itself.
There are occasions, when you have followed a specific pattern of clicks, where your editor keeps focus (where its title tab is blue) even when you have clicked elsewhere, such as an entry in another view. For example, when the DTD editor is open and the outline view is visible, do the following:
This behavior keeps the editor menu and action icon contributions active even while you interact with another view. You can still request the context menu for the entry selected in the view. The only issue is that this seems odd when the blue title is telling you that focus is still on the editor.
Some editors are affected by another issue related to how and when focus changes. Entries made in a text field only register as a change to the field when focus is lost. If you enter data in a field, such as the URI mapping field in the web.xml editor, and simply click on the gray area of the editor page, the data entered is not seen as a change to the field. The data entered registers as a change if you do any of the following things:
The editor will let you know a change has been registered by adding an asterisk (*) to the front of the file name shown in the editor tab.
Validation warnings and errors, compiler errors, and messages are displayed in the Tasks view. To paste the text into a file, select the rows of the relevant tasks, and drag the items to an appropriate editor (such as Wordpad). Your tasks will appear in a neat report format.
If you change the workbench fonts in the Preferences dialog to a non-DBCS font (for example, Arial) on a machine running a DBCS language, the DBCS characters will appear as question marks; this is expected behavior. However, when you change the font back to a DBCS-supported font, ensure you set the script setting on the font dialog at the same time you set the font. If you do not set both of these at the same time, then the DBCS characters will remain as question marks. Another solution to this problem is to click the Use System Font button on the Workbench Font Preferences page.
We recommend that DBCS users change the fonts used to display text in WebSphere Studio. You can change the fonts in the Fonts (Window > Preferences > Workbench > Fonts) page of the Preferences window.
We recommend you use the following fonts:
When a workspace created with a previous version of WebSphere Studio is opened for the first time in the current version of WebSphere Studio, you may encounter errors when a perspective is restored. If you do, select Window >Reset Perspective from the menu bar to restore the perspective. To avoid these errors, close all perspectives in your workspace in the previous version of WebSphere Studio before migrating to the current version.
A number of dialog boxes in WebSphere Studio, such as the Preferences dialog box, require a minimum display resolution of at least 800 x 600.
When an external tool is launched, expanded path variables that contain spaces are automatically enclosed in double quotation marks ( " " ). While it is typical for Windows programs to handle paths containing spaces to be in quotation marks, this is known to cause problems on other platforms. A workaround is to make a script for the external tool which strips off the quotes before launching the program with those parameters.
The Text file encoding value displayed in the Preferences dialog box under Workbench > Editors may be wrong on platforms running Windows XP (or 2000) when the user locale and system locale differ.
For example, suppose a user is using Japanese Windows 2000, but is working in the United States. The user has selected English (United States) as the user locale. The Text file encoding value displayed by WebSphere Studio is incorrect: Cp1252 (English). It should display the system locale: MS932 (Japanese).
To work around this, you can change the user locale so that the user locale and system locale are identical. In the example above, this means you should set Japanese as the user locale, then restart WebSphere Studio. The Text file encoding value will then be correct: MS932 (Japanese).
For Windows XP:
For Windows 2000:
Clients of action bars may create a number of SubToolBarManagers
on their IToolBarManager (for example, a multi-page editor). The client will
typically make one SubToolBarManager visible, the rest invisible,
and call updateActionBars. The visibility of the items may not
update correctly.
A workaround is for the client to explicitly update the toolbar:
actionBars.updateActionBars();
actionBars.getToolBarManager().update(false);
Certain shortcut keys do not work with an Arabic keyboard layout. You
can work around this by changing the keyboard layout to English.
If you import preference settings into WebSphere Studio that come from another installation of WebSphere Studio, you may receive compilation errors that refer to missing libraries. In order to reset the class path variables properly, close any open XML perspective. Then, close the workbench, restart it and open the XML perspective.
When you create a simple project in WebSphere Studio (File > New > Other Simple > Project) you should be prompted to switch to the Resource perspective, but you are not. To work around this, manually switch to the Resource perspective (Window > Open Perspective > Other > Resource) after you have created your simple project.
Linked resources and multiple output folders are not supported in this version of Websphere Studio.
When removing the key binding for the "Toggle Overwrite Mode" command on the Workbench > Keys preference page, the mode is still toggled when clicking the Insert key. The mode indication in the editor's status line is then out of sync with the actual mode.
If you have OutOfMemoryError problems when working with large projects and files, you can increase your heap size by using the -vmargs -Xmx500M command-line options when you start WebSphere Studio. Adjust the 500M (500 meg) to an amount appropriate for your situation.
The following are known problems with editors.
When you add markers to unsaved text, those markers are not properly updated or removed if the editor is closed without you saving the text changes. After you close the editor the markers may point to nonexistent or unrelated text regions.
The default HTML and JSP editor does not support bidirectional languages. If you are working with a bidirectional language, you should set up Page Designer "Classic" as your default editor for HTML or JSP files. To do this, select Window > Preferences > Workbench > File Associations and change the associations in this page. For more information about enabling Page Designer classic, and changing associations, refer to the Web tools readme.
When running on J9, it is recommended that you use the following VM options. Please refer to the J9 VM documentation and help for further information:
platform [arguments] -vm <path to j9w.exe> -vmargs -ms:20 -jit -mo:32000 -mx:200000
where platform is the name of the executable found in the top level directory of your installation and arguments are those arguments to be passed to the platform.
NOTE: the -vmargs flag and the actual VM arguments must come at the end of the line.
If you receive a program error in utc.dll then you must launch WebSphere Studio from its .exe file. The configuration settings file (in the same directory as the .exe file - it ends in .ini) must also contain the following entry in the [Environment Variables] section:
JITC_COMPILEOPT=SKIP{org/eclipse/ui/views/tasklist/TaskListContentProvider}{resourceChanged}
If you launch WebSphere Studio from the shortcut created in the Start menu then the entry has already been added.
If an Ant script is run as an external tool or using the Run Ant
pop-up menu, it runs on the same Java VM as WebSphere Studio. If the running script
executes any Ant task that calls System.exit(int),WebSphere Studio exits and
any unsaved work is lost. A workaround for these Ant tasks is to configure Ant
as an external tool. The following steps show how this is done:
- Download and install the binary version of Ant from http://jakarta.apache.org/ant
- Click Run > External Tools > Configure.
- Click New.
- Enter a name for your external tool (for example, External Ant).
- Click Browse File System.
- Find and select a file called
ant.bat(it should be in the bin/ folder of your Ant installation).- In the Tool Arguments field enter the arguments for your script that you would normally enter for running the script outside of the workbench.
- In the Working directory field enter the directory of your script.
- Click OK to exit the wizard.
- To run the script, click Run > External Tools > External Ant.
In Window > Preferences > External Tools, there is a group of radio buttons under the heading Preferred output level - Information, Verbose, and Debug. Changing these values does not affect WebSphere Studio in any way.
When
running an Ant script, use the Ant command line arguments -verbose
or -debug to get an output level other than the default
(Information).
WebSphere Studio's Ant UI correctly resolves entities with URI-based system values
specifying the "file:" protocol. Other formats and
protocols, such as a relative paths, "http:" URIs, and
so on are resolved by the user's default XML parser, which can vary by JRE, user
settings, etc. Parsers such as org.apache.crimson.parser, for
instance, expect valid URIs only and will fail on an entity reference such as
this:
<!ENTITY custom SYSTEM "../../custom.xml">
The workaround for this problem is to ensure you add the "file:"
protocol specifier to relative paths as follows:
<!ENTITY custom SYSTEM "file:../../custom.xml">
This problem only occurs in the UI, as WebSphere Studio's Ant execution engine uses SAXParser,
which correctly resolves formats such as relative paths.
Explicitly adding the Xerces JARs to the run-time Ant classpath is no longer
required and can cause problems. The Xerces classes are loaded from the
org.apache.xerces plug-in provided with Eclipse. For most Ant
distributions, the Xerces JARs cannot even be in the same physical location as
the ant.jar and optional.jar. This results from the
Ant JARs containing manifest files which contain classpath entries pointing to
the Xerces JARs.
Including the class files for custom Ant tasks or Ant types in the regular
code JAR for your plug-in causes problems. These class files must be provided in
a separate JAR that is contributed to the org.eclipse.ant.core.antTasks
or antTypes extension point (and not declared as a library in the
plug-in's manifest). This ensures that the Ant tasks and types are loaded by the
special Ant class loader and not by a plug-in classloader.
Eclipse runs Ant in the same JVM as the rest of WebSphere Studio. Several aspects of Ant and its use of global Java resources (such as System.out and System.err), make it unsafe to run more than one Ant build concurrently.
Certain Ant tasks are known to leak memory.
As with using Ant from the command line, prompts for input from the console is not handled. This is not the same as making use of the <input> task, which works correctly within WebSphere Studio.
Code completion provided by the Ant editor does not respect the
user-specified version of org.eclipse.ant.core plug-in or ANT_HOME.
Code completion proposals are always based on Ant 1.5.
Return to the main readme file
(C) Copyright IBM Corporation 2000, 2003. All Rights Reserved.