RDP LPEX profile

This page is intended to share the steps necessary to create a simple RDi 9.1 LPEX profile plug-in. This plug-in is an LPEX profile which runs when the editor is opened. Much of this is based on http://www.ibm.com/developerworks/websphere/library/techarticles/0607_casey/0607_casey.html

Switch to the Plug-in Development perspective

Window > Open Perspective > Other... Plug-in Development
Make sure you have the Package Explorer view available

Create a new plug-in project

In Capabilities, make sure that Eclipse Plug-in Development is enabled. You may need to click Advanced... and the expand Development.
File > New > Plug-in Project
Fill in the name of the project. This will become the name of the generated .jar file. Case is very important!

Click Next.
The next panel describes some of the details of the project. The defaults look good.

Click Next.
The next panel is asking if you want to use a template. Don't use a template.

Click Finish.

Set the plug-in properties

Overview

Look at the editor view on the right. There is a new tab there with your project on it. Click on the Overview tab.

The defaults look OK. Click on the Dependencies tab.

Click the Add... button to add a required plug-in.

Filter on com.ibm.lpex
Click on com.ibm.lpex
Click OK.
Click the Extensions tab

Extensions

Here we tell Eclipse about any extensions this plug-in will need. We're extending lpex.preload (for the Preload). (The screen shot says Activator.)

Click Add...

Filter on com.ibm.lpex
Select com.ibm.lpex.preload
Click Finish

The wizard generated a name for the extension that we don't want.
Click Browse...

On the Browse window, select Preload - com.kc2hiz.lpexextensions
- (the screen shot says Activator)
Click OK
Ctrl-S to save
Click on the Runtime tab

Runtime

This is the Runtime tab. We need to tell Eclipse that our soon to be completed plug-in is available for public use.

Under Exported Packages, click Add...

Select the class we're working on (here, com.kc2hiz.lpexextensions) and click OK.
Press Ctrl-S to save

TODO Start fixing

Create the Preload class

The Preload Java class defines a preload method. This method, which is invoked by the LPEX editor when it initializes, defines our user profile class as the default user profile.

To create the class:

In the Package Explorer view, expand the src folder and right-click the com.mycompany.lpexExtensions package. In the context menu select New - Class. In the New Java Class window, verify that the Source Folder and Package fields are prefilled with com.mycompany.lpexExtensions/src and com.mycompany.lpexExtensions, respectively, which appear because you started the New Java Class wizard from the package folder. Enter Preload in the Name field. Click the Add button next to the Interfaces text box. In the Implemented Interfaces Selection window, enter lpexp in the Choose interfaces field, which shortens the list as you type. Select LpexPreload and click OK. This step adds com.ibm.lpex.alef.LpexPreload to the Interfaces box. Click Finish to create the class and open it for editing. In the editor for Preload.java, add this statement after the existing import statement:

						import com.ibm.lpex.core.LpexView;

In the editor for Preload.java add this statement to the preload method:

						LpexView.doGlobalCommand("set default.updateProfile.userProfile 						com.mycompany.lpexExtensions.UserProfile1");

Press Ctrl+S to save your changes. Verify that your code looks similar to what is shown in Listing 1. You can ignore the comments. Make sure that there are no errors. Close the editor for Preload.java.

Listing 1. Completed Preload class definition (template generated comments have been removed)

package com.mycompany.lpexExtensions; import com.ibm.lpex.alef.LpexPreload; import com.ibm.lpex.core.LpexView; public class Preload implements LpexPreload { public void preload() { LpexView.doGlobalCommand( "set default.updateProfile.userProfile com.mycompany.lpexExtensions.UserProfile1" ); } }

Create the user profile class

You implement the LPEX editor user profile as a Java class with a userProfile method. You then code the LPEX customizations by invoking LPEX commands and actions in the userProfile method.

To create the class:

In the Package Explorer view, expand the src folder and right-click Specifiy the destination directory for your plug-in the com.mycompany.lpexExtensions package. In the context menu select New - Class. In the New Java Class window, verify that the Source Folder and Package entry fields are prefilled with com.mycompany.lpexExtensions/src and com.mycompany.lpexExtensions, respectively. Enter UserProfile1 in the Name field. Click Finish to create the class and open it for editing. In the editor for UserProfile1.java, add the two import statements after the package statement, as shown in Listing 2. Add the userProfile method and all of its statements as shown in Listing 2. Press Ctrl+S to save your changes. Verify that your code looks similar to what is shown in Listing 2. You can ignore the comments. Make sure that there are no errors. Close the editor for UserProfile1.java.

Listing 2. Completed UserProfile1 class (template generated comments have been removed)

package com.mycompany.lpexExtensions; import com.ibm.lpex.core.LpexAction; import com.ibm.lpex.core.LpexView; public class UserProfile1 {

   public static void userProfile(LpexView lpexView) {
     // define new action
     lpexView.defineAction("insertSemicolon2Action", new LpexAction() {
        public void doAction(LpexView view) {
            // go to the end of the line
           view.doAction(view.actionId("contextEnd"));
           // insert a semicolon and comment string
           view.doCommand("insertText ; /*  */");
           // position the cursor in the middle of the comment
           view.doAction(view.actionId("left"));
           view.doAction(view.actionId("left"));
           view.doAction(view.actionId("left"));
        }

        public boolean available(LpexView view) {
           // allow the action to run for any visible text line in a writable document
           return view.currentElement() != 0 && !view.queryOn("readonly");
        }
     });
     // Assign keys "Ctrl+5" to run insertSemicolon2Action
     lpexView.doCommand("set keyAction.c-5 insertSemicolon2Action");

     // set ispf as default editor style
     lpexView.doDefaultCommand("set default.updateProfile.baseProfile ispf");
     /* lpexView.doDefaultCommand("updateProfile"); */
  }

}

Test your user profile plug-in

Eclipse provides a runtime environment, the runtime workbench, for testing plug-ins as they are being developed. To start the runtime workbench:

Go to the Overview page in the editor for plugin.xml (click the Overview tab). On the Overview page, click Launch a runtime workbench, which starts another instance of WebSphere Developer for zSeries that can access your plug-in code.

Observe the effect of the Preload class Open the Preferences page by selecting Window - Preferences from the menu bar. In the Preferences window, expand LPEX Editor (on the left), and select User Profiles. Because the Preload method was invoked during the initialization of the workspace, Class name has been set to com.mycompany.lpexExtensions.UserProfile1 as shown in Figure 2. This is the default user profile. Figure 2. Default user profile set by Preload class Click Cancel to close the Preferences window.

Test the user profile

To test your new action, you need to open a file in the z/OS LPEX editor. An easy way to do this is to create a new project using sample code shipped with WebSphere Developer for zSeries. Since our user action supports the PL/I syntax of ending a command with a semicolon, we will use a PL/I example.

To test your action:

From the menu bar, select File - New - Example In the New Example window, expand Examples, expand Workstation PL/I, select PLI Sample 1, and click Next. On the z/OS Local Project page, enter PLITest in the Project name field and click Finish. If the Confirm Perspective Switch dialog box appears, click Yes. In the z/OS Projects View, expand the project PLITest, expand the folder pli, and double-click on HelloApp.pli to edit it. Position your cursor at the beginning of a line with text, and then press Ctrl+5. Your new action is executed, placing a semicolon at the end of the line and inserting a new line below. Your action can also be run from the command line using the action command. Position your cursor at the beginning of a line with text, and then press Esc, which will place the cursor in the command line. Enter action insertSemicolon2Action in the command line area and press Enter. Your new action is executed. When you are finished testing your new action, close the editor for HelloApp.pli. You do not need to save the changes. In the test workbench window, select File - Exit from the menu bar to close the workbench window.

Deploy the plug-in to WebSphere Developer for zSeries

To deploy the plug-in, you first need to export it from the PDE, and then copy it to your WebSphere Developer for zSeries installation directory.

Export the plug-in from the PDE

During development, plug-ins in your workspace are used as-is so that you can quickly test and debug them. When you are satisfied with the operation of your new plug-in, you will want to publish this plug-in so that others may use it. The easiest way to publish your plug-in is using the Export Plug-ins and Fragments Wizard:

In the Package Explorer view, right click on com.mycompany.lpexExtensions and select Export... from the context menu On the Export window, select Deployable plug-ins and fragments in the list box and click Next. In the Export Plug-ins and Fragments window, check the box for com.mycompany.lpexExtensions, which is listed in the Available Plug-ins and Fragmentstextbox. In the Export Options field, select a directory structure from the list. You can deploy plug-ins in one of three formats: A single ZIP file whose content can be unzipped into any Eclipse-based product. A directory structure, so that the plug-in can be placed directly in an Eclipse installation, such as the plug-in directory for WebSphere Developer for zSeries. Individual JAR archives for an update site. This option creates one JAR per plug-in, and places the JARs in a /plugins/ subdirectory of the chosen destination.

For the Directory field, use its Browse button to navigate to the \wdz\eclipse folder in the WebSphere Developer for zSeries installation directory. The Directory field should look like Figure 3 if you used the default installation directory of C:\Program Files\IBM\Rational\SDP\6.0.Figure 3. Specifiy the destination directory for your plug-in Click Finish to start the build process, which displays a message dialog that the build is in progress. You do not need to press any of the buttons. When the build is finished, the dialog box will close.

Verify that the plug-in works Stop WebSphere Developer for zSeries and restart it. Verify that the user profile has been added to the the LPEX editor User Profile page in the Preferences view. Open a PL/I file in the LPEX editor and verify that insertSemicolon2Action works.

Conclusion

User profiles ease the customization of the LPEX editor. They eliminate manual definition and provide a way to organize editor settings for special tasks. In this article, I showed how to extend the LPEX editor in WebSphere Developer for z/Series to automatically load a user profile when the editor opens. By following the steps in this article, you have a model by which you can create your own user profiles for the LPEX editor.

Export the plug-in

At this point, all of the code is written. Yes, those two little Java files make up the plug-in. Well, them and the MANIFEST.MF and plugin.xml. And build.properties helps with the process of keeping all the pieces aligned in the IDE. The export process packages up all the necessary .class files and other anciliaries into a single .jar file which then can be deployed into any RDi configuration and used after a restart.

Export wizard

Click on the Overview tab

Click on the Organize Manifests Wizard link

Click Finish
Click on the Export Wizard link

It's important to export as a directory. Record the export location; you'll need it to deploy the plug-in.
Click Finish
Close RDi

Copy jar file

Open Windows Explorer
- Position to the directory you recorded above. Here, it's c:\buck\rdi9
- Open the plugins folder
Open a second Windows Explorer
- Position to the directory where you installed RDi. Here, it's c:\Program Files\IBM\SDP
- Open the plugins folder

Copy the .jar file from the export directory into the SDP\plugins folder.

Set up RDi to use the new plug-in

Start RDi. If you've been tinkering with this plug-in, you might want to use the -clean parameter. I keep a separate icon with that option. We're now going to tell RDi about our new plug-in and assign it to a keystroke.

User Actions

First, tell RDi that we have a new user action available.

Windows > Preferences
LPEX Editor
User Actions

Give the action a name. I find it simplest to name it the same as the Java class.
Identify the class that implements this action. Here, it's com.kc2hiz.lpexextensiotn.ToPrefixAreaAction
Click Set
Click Apply

User Key Actions

Finally, assign the user action to a keystroke. I chose Ctrl + ` (the back-tick, below Escape and above Tab).

Windows > Preferences
LPEX Editor
User Key Actions

Give the action a name. I find it simplest to name it the same as the Java class.
Identify the class that implements this action. Here, it's com.kc2hiz.lpexextensiotn.ToPrefixAreaAction
Click Set
Click Apply

Give the action a name. I find it simplest to name it the same as the Java class.
Assign a key. Here, it's c-backQuote.p. The trailing .p tells Eclipse that we want to enable this keystroke in the prefix area
Fill in the name of the action assigned above. Here, it's ToPrefixArea
Click Set
Click Apply
Assign the same key, but this time with a trailing .t which tells Eclipse we want to enable this keystroke within the text area
Fill in the name of the action assigned above. Here, it's ToPrefixArea
Click Set
Click Apply
Click OK

Now test the new action by pressing Ctrl-` multiple times inside an IBM i source member. The cursor should move between the rprefix area (line numbers) and the text area( the editable source).

RDP LPEX profile

Contents

Switch to the Plug-in Development perspective

Create a new plug-in project

Set the plug-in properties

Overview

Extensions

Runtime

TODO Start fixing

Export the plug-in

Export wizard

Copy jar file

Set up RDi to use the new plug-in

User Actions

User Key Actions

Categories

Navigation menu

Views

Personal tools

Navigation

Search

Tools