Troubleshooting Tips

The following topics describe problems that you might encounter when using Microsoft® J/Direct™. For each situation, possible solutions are provided.

UnsatisfiedLinkError When Calling a Method

Getting SecurityException When Calling a DLL Method or Using an @dll.struct Class

StringBuffers Truncated on Return From DLL Function

Mysterious Syntax Errors Within @dll Directives

Compiler Cannot Find Basic System Packages Like java.lang

Compiler Cannot Find the com.ms.dll Package

Syntax Errors When Using J/Direct with Inner Classes

@dll Directives Do Not Work on Applets (or Only Works Within the Microsoft Visual J++ Environment)

Using J/Direct Makes Class Unusable

J/Direct Throws a ParameterCountMismatchError After Calling a Native Function

J/Direct Does Not Unload a DLL

UnsatisfiedLinkError When Calling a Method

• Check the version of your compiler to see that you have a compatible compiler. (To display the version number, execute jvc with no arguments on the command line.) The Microsoft SDK for Java supplies a version of the compiler that supports J/Direct. See the SDK release notes for the version number that corresponds to that release. If your compiler does not support J/Direct, the Microsoft Win32 VM for Java will attempt to link native methods using the Raw Native Interface and will not succeed.
• Make sure your DLL is visible on the system path. DLLs are searched for in the following locations (in order):
  1. The directory from which the application (typically jview) loaded.
  2. The current directory.
  3. The Windows system directory.
  4. The Windows directory.
  5. The directories listed in the PATH environment variable.

  The Microsoft VM will not attempt to load the DLL until a method requiring it is actually called. Therefore, do not assume that the DLL load was successful simply because the Java class loaded successfully.

• Check the method qualifiers. Methods declared with the @dll.import directive must be native and static. They can have any level of access (public, private, and so on) supported by the Java language.
• Make sure that your method name matches the DLL export name exactly, including capitalization. The DLL linking mechanism in Win32 is case-sensitive.
• If you still have trouble linking to a method, use a utility such as dumpbin/exports (Visual C++) to verify that the DLL exports the method by the name you are using. Some DLLs may require you to link to exports by ordinal (an integer) rather than a name. In such a case, use the entrypoint override on the method using the "#ordinal" syntax as in the following example.

  
    // This method is exported as ordinal #34.
    /** @dll.import("MyDll",entrypoint="#34") */
    public static native void MySample();
  

• Be aware that some so-called functions are actually C macros and the actual DLL export name may be quite different from the name of the macro.

Getting SecurityException When Calling a DLL Method or Using an @dll.struct Class

DLL calling and the use of @dll.struct classes is restricted to Java applications and signed Java applets. For more information about signing applets, see the article on Signing a Cabinet File with Java Permissions.

StringBuffers Truncated on Return From DLL Function

You must ensure that the StringBuffer's capacity is sufficient to contain the string you need before you invoke the DLL function. You can specify the capacity in the StringBuffer's constructor, and you can use the StringBuffer.ensureCapacity method to guarantee a minimum capacity prior to the DLL call.

Mysterious Syntax Errors Within @dll Directives

Extra white space within @dll.import and @dll.struct directives can cause syntax errors. Avoid using white space inside @dll constructs.

Compiler Cannot Find Basic System Packages Like java.lang

The compiler shipped with SDK for Java looks for system packages in the classes.zip file. This conflicts with the new Package Management scheme used by the Microsoft VM, which stores system packages as .zip files with obfuscated names under the %WINDIR%\java\packages directory. Unfortunately, the Java Language Compiler has not yet been updated to recognize this new scheme. To compile Java programs against the new VM, you must create an old-style .zip file and ensure that it is included in the CLASSPATH.

Normally, the SDK installation program does this for you. If, however, you installed the SDK by some other method, or if your configuration has been corrupted since the installation, you may need to recreate CLASSES.ZIP. The easiest way to do this is to type clspack -auto at the MS-DOS® command prompt. This will create a single CLASSES.ZIP in your %WINDIR%\java\Classes directory that contains all classes stored in the package manager. The Microsoft compiler for Java looks for classes in this location by default, so there is no need to set your CLASSPATH environment variable.

Compiler Cannot Find the com.ms.dll Package

An older version of classes.zip is being used. Try renaming all older versions of classes.zip on your disk drive and follow the instructions under Compiler Cannot Find Basic System Packages Like java.lang for creating a new classes.zip file.

Syntax Errors When Using J/Direct with Inner Classes

The version of the Java compiler that ships with the SDK for Java does not correctly handle @dll directives on inner classes or classes that contain inner class declarations.

@dll Directives Do Not Work on Applets (or Only Works Within the Microsoft Visual J++ Environment)

Because the use of J/Direct can compromise security, its use is restricted to Java applications and signed Java applets. See Signing a Cabinet File with Java Permissions for more information about signing applets.

Using J/Direct Makes Class Unusable

Any use of J/Direct within a class marks that class as unsafe and unusable by untrusted code, even if the J/Direct methods are not actually invoked.

J/Direct Throws a ParameterCountMismatchError After Calling a Native Function

The ParameterCountMismatchError exception alerts you to the fact that the called function consumed (popped off the stack) more or fewer parameters than was passed by J/Direct. This error normally indicates that the parameters in the Java method declaration do not match up with the parameters expected by the DLL function.

If the function pops off no arguments, it is assumed to be using the cdecl calling convention and an exception is not thrown, even if the Java method declares a non-zero number of arguments.

Caution You should not attempt to catch and deal with the ParameterCountMismatchError exception. This exception was designed to assist developers in catching bugs during the development stage. For performance reasons, parameter count checking is performed only when the application is running under a Java debugger. It is also important to note that J/Direct performs this check after the function call has been completed. Because this exception indicates that one or more invalid parameters might have been passed to the function call, it cannot be guaranteed that the process can recover.

J/Direct Does Not Unload a DLL

J/Direct unloads a DLL when the Microsoft VM discards the Java class that imported the DLL. For a Java application running under jview, this does not occur until the process exits. For a trusted Java applet, this happens at some undetermined time after the browser has left the page containing the applet. The Microsoft VM attempts to keep Java classes loaded for several pages afterward in order to optimize applet refresh time in case the page is revisited.

If you need explicit control over the loading and unloading of DLLs, you need to call the Windows loader explicitly and use the call entrypoint to invoke functions dynamically. For more information on how to do this, see the section in this article on Dynamically Loading and Invoking DLLs.