J-Link can seem intimidating at first, but once you have all the little pieces in hand to get started, it's actually pretty simple. In this article, I'll walk you through all the pieces that you need to create a basic J-Link application.
Even a simplistic J-Link program requires several files, including your Java code compiled to class file(s), a text-based "message file", and an auxiliary application "registry file". I'll explain the required content of each file and how to put them all together.
The Registry File
The registry file is used to instruct Pro/Engineer on how to load an auxiliary application, such as a Pro/Toolkit or J-Link program. Pro/Engineer uses this to find all of the program's pieces. The actual name of the file is not that important, but "protk.dat" will be used as the filename in this example.
An auxiliary application can be started by Pro/Engineer automatically by using the PROTKDAT config.pro option, or by placing the registry file in certain special locations (i.e. the working directory, within the Pro/Engineer install, etc). Auxiliary applications can also be started manually.
Here is an example registry file for the J-Link "Hello World" application:
The "name" will appear in the auxiliary application dialog to aid in identifying the program and can be as descriptive (or cryptic) as you need. The "startup java" entry is required for J-Link apps.
"java_app_class" indentifies the primary class of the application where the "java_app_start" and "java_app_stop" methods are contained. The program is required to have static "stop" and "start" methods matching the names given in the registry file (more on that later).
The "allow_stop" option allows the user to stop the program if it is running. The "delay_start" option (if set to "true") can disable automatic startup allowing the user to do this later, manually, if desired.
The "text_dir" option identifies the folder hierarchy containing your application's message files. Although the inclusion of the "text" folder in the path is not always required, it doesn't cause any problems. Unix style paths work just fine here, as they do with config.pro files. Consult my other articles about cool stuff with registry files.
"java_app_classpath" is generally used to find other class and jar files that you may use in your application. It's like having a private CLASSPATH environment variable for each program. As an alternative, this option can be replaced by using the ADD_JAVA_CLASS_PATH config.pro option, using the same value. However, keeping the option in the registry file is generally the simpler approach.
Not every entry is required, but it's usually a good idea to use the above set for greater flexibility.
The config.pro File
To initiate the program upon startup of Pro/Engineer, you can use a PROTKDAT config.pro option. The value of this option is the full path to the registry file.
Using the above example, the option might look like this:
The Text Message File
The text message file is used primarily to support internationalization. However, it also enables "code vs data" separation by relocating static text to standalone files. A text message file is needed for even the most basic J-Link program.
Each "entry" in a text message file is comprised of four lines. Typically only the first two are used, the last two are placeholders. The first line is the "message id" that you use in your code, and the second line is the text that will generally appear for that message id.
In this example, the text message file msg_jlinkhelloworld.txt will contain three entries as follows:
JLHW Btn1 Label
JLink Hello World
JLHW Btn1 Help
Run the JLink Hello World Application
Be sure to leave an extra blank line at the end of the file to avoid one of the many strange problems with text message files.
The text message file must be placed within the folder structure specified by "text_dir" in the registry file. In this example application, the text message file will be placed in:
Proper location of the text message file is very critical. Putting the file in the wrong folder is the source of confusion and frustation to new Pro/Engineer API developers.
Read Part 2 for the Java code