Main JAR Packager Native JFC Technical Support What's New dbDE

Copyright (c) 1998 by Symantec Corporation. All Rights Reserved. Visual Cafe is a trademark of Symantec Corporation. Other brands and their products are trademarks of their respective holders.



I. Welcome
II. Installation Notes, JFC and KL Group
III. User Tips
IV. Known Problems and Caveats
V. Questions and Answers

I. Welcome

Visual Cafe uses the CLASSPATH from the sc.ini file in the <"VCafe">\Bin directory. The CLASSPATH in sc.ini, by default, does not contain the environment classpath (i.e.,%CLASSPATH%). Existing projects relying on the environment classpath setting may fail to build. To correct this, you may either add the package directories manually to the sc.ini classpath, add the package directories to the project in project/options/directories, or add the %CLASSPATH% variable to the end of the classpath line in the sc.ini file.

On a final note: The SC.INI file is required for Visual Cafe to correctly operate.

Remote Debugging

To pass arguments to the VM for debugging applications:

1. Open a command line window in the directory with your Main class. Execute the line below. XXXX are the arguments you want to pass, e.g. -ms16m, -mx128m.

java_g -debug -XXXX symantec.tools.debug.EmptyApp

This will print: Agent password=yyyy

2. In the menu go to: Project | Options... | Debugger. Enable Remote Debugging. Set the Host Address to 127.0.0.1. Set the password to the output you got from the command line in step 1.

3. You may now begin debugging normally.

4. When you are finished, do <ctrl-c> in the command line window to end the session.

5. To start another session, do step 1 to get a new password.


Executing & Debugging applets in Netscape Navigator

Visual Cafe now supports the ability to debug Java applets using Netscape Navigator. You must have version 4.04 or later of Netscape Communicator installed on your system. In addition you must have the updated support for JDK 1.1 to do this. You may obtain this from Netscape's web site at http://developer.netscape.com/software. Make sure you install the support patch for version 4.03 or greater.

In order for Visual Cafe to execute your applets in Netscape Navigator, you need to edit your project options and select "Execute applet in default web browser." You will also need to ensure that Netscape Navigator is configured as your default browser.

Netscape will issue some security violation exceptions when you attempt to execute or debug applets from within Visual Cafe. To avoid this security constraint, please add the following options to your prefs.js file:

user_pref("unsigned.applets.low_security_for_local_classes", true);
user_pref("signed.applets.local_classes_have_30_powers", true);
user_pref("signed.applets.low_security_for_local_classes", true);
user_pref("signed.applets.verbose_security_exception", true);

Notes:

1. This file states that it should not be edited by hand. In order to add entries to this file, you must first close all running instances of the Netscape Navigator. You may then edit the file manually.

2. You will see a message in the Java console, "# Security Exception: checkpropsaccess.key". This message can be ignored.

For more information on Netscape security please refer to following URLs:

http://developer.netscape.com/support/faqs/champions/security.html
http://developer.netscape.com/library/technote/security/sectn3.html


Executing & Debugging applets in Microsoft's Internet Explorer

In order for Visual Cafe to execute your applets in Microsoft's Internet Explorer, you need to edit your project options and select "Execute applet in default web browser." You will also need to ensure that Microsoft's Internet Explorer is configured as your default browser.

The Microsoft browser does not support JNI, the native code required by Sun's JDBC-ODBC Bridge. Microsoft has its own version of the JDBC-ODBC Bridge, which can be obtained by downloading the
Microsoft SDK for Java from their website.



Source Control
Visual Cafe supports the ability to manage source files (such as .java) from within the environment through a version control system such as Starbase Versions. Because of the special nature of the project file (.vep), checking this in or out must be done outside Visual Cafe with the project closed. The procedures are:

Checking out the project file:
1) Close the project in Visual Cafe.
2) Check-out or get the .vep file
3) Delete the .vpj and .ve2 files from project directory.
4) Now open the project.

Checking in a project file:
1) Close the project in visual cafe.
2) Check-in the .vep file

NOTES:

* The .vep file is a binary file.

* It is not recommended that the .vpj and .ve2 files be kept under version control since these are binary files. If you do elect to check them in, make certain that they are not marked read-only. If you do, Visual Cafe will be unable to open the project.

* Visual Cafe offers and API to allow checking in of .vep files into the source control. Source control vendors are working on integrating this ability.


IV. Known Problems and Caveats

This section lists information about known problems:

* If you encounter certain errors when starting Visual Cafe or if your tool palette appears empty, delete the following files from \VisualCafe(WDE|PDE|dbDE)\Bin:

*.rps
*.reg
*.vws

Note: Some of the errors are:

"No starter templates could be found"
"Cannot open local repository"
"Cannot open registry"

These files are platform-dependent and must be regenerated when switching from one operating system or to another machine.


* When using the Parse All Imports option, we recommend that you allow the parser to finish parsing before editing or changing a file. To view the status of the parser, select Messages from the Visual Cafe Window menu.

* Java Beans custom painters (e.g. any implementation of PropertyEditor.paintValue will not be called).

* Under Windows 95 it is best to drop larger JAR files one at a time. This is a problem with the Java VM under Windows 95, and we expect it to be resolved in version 1.2 of the Java VM.

* Visual Cafe uses the code generation model. If a bean has a property editor, the method PropertyEditor.getJavaIntializationString() must be properly implemented.

* In some cases, stepping over a statement in a try block that triggers an exception will cause the app to terminate. To get around this, set a breakpoint in your catch block. This breakpoint will get hit and you can continue to debug.

* Using the menu item File > Open Page in the Netscape browser to load html pages which contain applets may not work due to various security constraints and security exceptions. We anticipate that these problems will be resolved in future versions of Netscape browser. These html pages normally work in deployment scenarios.


* Jar Viewer: The manifest display is limited to 32K of text. To view Manifest files that are larger than 32K, multi select (shift-click) the entries in chunks less than 32K at a time.

* Custom property editors: All custom property editors must be serializable; otherwise Visual Cafe cannot initialize the state of the bean.

<<PDE and DbDe only>>
* Netscape can crash if a breakpoint set in code for a timer_event is hit while debugging.

* Occasionally, when debugging in browsers, actions may lead to an attempt to open source files which are not available. In such cases, simply dismiss the open file dialog box and continue debugging by choosing Debug > Continue or the Run in Debugger arrow button.

* Hitting a breakpoint in the run() method of an applet within Netscape Communicator implementing Runnable will cause Visual Cafe to crash.

* When debugging in Netscape or Internet Explorer, stepping into code for components will use the browsers' VM. Line-number info will be incorrect, thus the code displayed will not be correct.
<<end PDE and DbDe only>>


Low-memory warning on startup

If the sum of your system's available physical memory (RAM) and swap space on disk is below a minimal level when Visual Cafe starts up, a warning dialog will notify you of this condition. It advises you to increase swap space (see below). You have the option of ignoring this warning (answer "No" to the "Quit?"prompt), and proceeding to run Visual Cafe. With light use, you may not experience any problems at all. But with typical use, at some time in the course of your Visual Cafe session you may begin to see "low virtual memory"warnings from the operating system. Typical symptoms of running any complex application with too little available memory are sluggish performance and unstable system behavior.

If the warning dialog recommends that you increase swap space by some small amount, such as 2 or 3 MB, increase the minimum swap space on Windows NT or free disk space on Windows 95 by at least 5 MB.

For Windows 95, if the option is selected in Settings > Control Panel > System > Performance > Virtual Memory to let the OS manage swap space (this is the default), then available swap space is simply the amount of free disk space; but note that there is no guaranteed minimum: if the disk is full, there is no swap space available.

For Windows NT 4.0, the Control Panel is started from the Settings menu item, as on Windows 95. The page file setting that matters most to an application under NT is the minimum page size setting. On a system with 32 MB RAM, the minimum swap space should be not less than 20 MB, and 32 MB is better. A reasonable setting for the maximum is at least twice the minimum.

For further details about virtual memory, see the OS Help in the System dialog box.


JDK Version Incompatibilities

Symantec Visual Cafe 2.5 supports version 1.1.5 of the Java Development Kit from Sun Microsystems.

Please see http://www.javasoft.com for information regarding specific OS incompatibilities with the JDK.


Java Beans
-----------------------------------------------------------------
When a bean has multiple types of event listeners that implement event types having the same name, Visual Cafe will generate code to handle that event type only for the first listener. If you select that event type for the second event listener, it will generate the code for using that event type from the first listener.


Converting Visual Cafe 1.0x projects
-----------------------------------------------------------------
When converting a 1.0 project that used a card layout with unnamed cards, the backparse will fail. To work around this, you must manually edit the add() statements for those cards without names. It is important to note that JDK 1.1 has disallowed unnamed cards in a card layout; the same code would also fail at runtime.


<<PDE and DbDe only>>
Native compiler

When using 3rd party classes (and components) in a native code compiled project, you must do one of the following two tasks:

o include the source for these classes as part of the project

o pre-compile the source for these classes to a native DLL and have the import library for that DLL listed in the Libraries section of the Compiler Project Options.


Native compiler and Visual Cafe 1.x and Cafe 1.x

If the sj.exe from Visual Cafe 1.x or Cafe 1.x is specified in the path before Visual Cafe 2.5, an invalid flag error -link will result when using the native compiler. To avoid this error, make sure that the sj.exe from Visual Cafe 2.5 is specified in the path first.
<<end PDE and DbDe only>>


Z-order of heavyweight components

Z-order of heavyweight java.awt components is undefined in JDK 1.1.5. As of this writing, the current JDK 1.1 versions of Internet Explorer and Netscape both use the same z-order. However, this may not be true in future versions of either browser or of other Java execution environments.


Lightweight component behavior between JDK 1.1 and 1.1.5

Between JDK 1.1 and JDK 1.1.5, behavior of lightweight components has changed in many ways (primarily to fix problems in the initial implementation). If you run your program in an environment with an implementation of lightweight components that is earlier than the implementation in JDK 1.1.5, behavior of the lightweight components may vary.


<<PDE and DbDe only>>
Incremental Debugging

Changes made to static variables require a restart of the application or applet before they will take effect. Similarly, changes made to methods in the active call chain will require a restart of the method before they can take effect. In both cases a dialog will present you with this choice.

When using incremental debugging, changes made do not take effect until the next time the modified method is called. This means if you modify a method that runs only once during the execution of your applet or application (e.g. init for an applet, run for a thread, a constructor for an already loaded class, etc.) AND that method has been executed, then you will need to restart the applet or application. The debugger
does not always detect this case and you may not get a prompt to restart. Also, if you modify static initializations, then you will need to restart the app as static initialization is done once the class is loaded. The environment does detect this case and will present the user with the appropriate prompt.

See the topic "Incremental debugging features" in the online help files for more features and expected behavior using incremental debugging.
<<end PDE and DbDe only>>


V. Questions and Answers

How do I register Starbase Versions?

Versions 2.0 provides intuitive version control for individuals and local groups of developers using Windows 95 and Windows NT. Register for the full version at http://www.starbase.com/verreg.htm
or phoning (714) 442-4460 CODE: VISUALCAFE97


How do I distribute my applet on a Web server?

The easiest solution is to JAR your applet by choosing the menu item Project > JAR... The resulting JAR file can be specified in your HTML file by using the ARCHIVE tag.
For example, if you create an applet with the name of foo and from that project you create a JAR file with the name of bar.jar, then within the HTML file you would specify:

<APPLET CODE="foo.class" ARCHIVE="bar.jar" WIDTH=250 HEIGHT=250>
</APPLET>

Not all browsers currently support the use of .jar files. To address this you can create the JAR and then "unJAR"the file.

To unjar your previously created .jar file go to a DOS command line and enter the command:

\VisualCafe(WDE|PDE|dbDE)\Java\Bin\jar.exe xf jarfilename.jar

The resulting directory tree of supporting class files can then be transferred via FTP to your Web space.

Note: the manifest.mf file is not needed to deploy.



What is the "Execute applet in default HTML viewer" option in the Project Options dialog?

The "Execute applet in default HTML viewer" option, located in the Project Options dialog box, allows you to view your applet in your favorite Web browser, instead of the AppletViewer,
when executing from the Visual Cafe environment.


Will Visual Cafe recognize my own source code?

When adding controls directly within the source editor, we recommend that you adhere to the same coding style as generated by Visual Cafe. This will allow controls you add to be displayed in the form editor. Controls you add outside Visual Cafe's tags (which are comments that indicate where Visual Cafe generates Java code for the form editor) will not be displayed in the form editor and will not be affected by automatic code generation.

If you are adding controls within Visual Cafe's tags in the source editor, you should adhere to Visual Cafe's coding style. Otherwise, you can add controls outside of Visual Cafe's tags using your own coding style.


When I open a project in the Form Designer, the dialog for Dial Up Networking appears. If I log on, all is well. If I cancel, Visual Cafe "hangs" for several minutes.

The use of relative URLs (for example, IMAGES/test.gif) can cause this behavior on some systems. To avoid it, use absolute URLs (for example, file://C:/.../PROJECT/IMAGES/test.gif) during design time and then switch to relative URLs for deployment.


How can I increase the size of a form within the Form Designer larger than the resolution of my screen?

A form in the Form Designer is limited to the resolution of your display. If your display system is capable, increase the its resolution to allow more information on the screen such as changing from 800x600 to 1024x768. If your display system supports the use of a "viewport" or "virtual desktop" where only a portion of the desktop is displayed on the monitor, the form size can be increased to the size of the desktop. Note that this has not been thoroughly tested with all display systems and is a function of your video card driver.


I would like to distribute my applications created with Visual Cafe along with the Symantec Virtual Machine. Do I need to obtain a license to distribute the Symantec JIT/JVM?

Yes. Please email jit-licensing@devtools.symantec.com. The .class files included with Visual Cafe are freely distributable. JavaSoft has licensed the Symantec JIT for redistribution in the JRE. The JRE is Sun's Java Runtime Environment and is freely redistributable. Please visit http://www.javasoft.com for more specific information regarding the JavaSoft JRE.


I place a component on top of another and yet it seems to
disappear underneath the other component.

The new JDK supports both lightweight and heavyweight components (see the online help files for a brief discussion of what constitutes a lightweight component). Lightweight components will always be drawn behind heavyweight components. For example, if you drop a Canvas component onto a form and then drop a Label3D component on top, the Label3D still is drawn beneath the Canvas because the Label3D is lightweight and the Canvas is heavyweight.


Thank you for using Visual Cafe 2.5 for Java. We are confident that it will enhance and improve the productivity of your development efforts.

Sincerely,

The Internet Tools Team