Creating And Using i Project

In my previous tip, I introduced i Projects and some ways in which I use them in my development life. In this tip, I’ll show you how to create and populate your projects, and how to make use of them.

Let’s first create an i Project. The easiest way to get started is to go into the i Projects perspective that is built in to RDP. WDSC also allows for the use of Projects, only they are called “iSeries” Projects. If you’re new to the tool and haven’t mastered opening a perspective, there are many ways to do it. I’d recommend that you use the Window menu option to “Open Perspective.” If you don’t see i Projects (or iSeries Projects in WDSC), then use the Other option to find and open it.

Once you’re in the i Projects perspective, you’ll see it highlighted in a tab at the top right of your workbench, as shown in the next graphic. You may be able to see only one perspective name in that tab. If so, I’d recommend stretching the tab (by dragging the left edge further left) until you can see all the perspective names you use on a regular basis. For me, that will be Remote Systems (or my own version of it), i Projects, and Debug, as you can see in the picture. That way, I can easily click on one of those three names in the tab to switch back and forth between them.

(Click graphic to enlarge.)

You can see the i Projects Navigator view is in the upper-left, that’s where the Remote Systems view is in the default RSE perspective. You’ll notice that the Remote Systems view isn’t gone, it is now below the i Projects Navigator. Otherwise, this perspective doesn’t look dramatically different from the RSE perspective. That’s by design, because working with i Projects is very much like working with Remote Systems except in how you interact with the source code. Of course, if you have never created an i Project, your i Projects Navigator will be empty. Let’s change that situation next. Feel free to follow along to create a project for practice. It’s very simple to clean it up later.

Create an i Project by right-clicking on a blank area of the i Projects Navigator view. Then choose New→IBM i Project. You’ll see a wizard dialog and be prompted for a Project name. Provide a name that makes sense for your project. In my figures in this and the earlier tip, I’ve depicted a project with the same name and even most of the same content as an existing library on the host. This is actually a very usual situation. I architected that example for the first tip to illustrate the similarities between working with i Projects and Remote Systems, but this tip is more about how they are different. So this time, I recommend that you don’t use a library name but instead choose a name that makes sense for the task you’re working on. As I suggested in the earlier tip, I sometimes use a problem or work order number or a client or class name as my project name. Press “Next” after you have entered a name for your Project.

(Click graphic to enlarge.)

On the next screen you’ll be asked to specify your host connection name. Chances are many of you will only have one connection, I have many because of the different environments that I work in. You also need to specify the host library that contains the source code you want to put into this project. Here we get into a big limitation of projects–they can only contain things from one library. There are tricks some people play to get items from multiple libraries into a single project, but I’ve never found that worth the effort. If I need source from multiple libraries, I create multiple projects.

(Click graphic to enlarge.)

After you enter a library, you’ll notice that you can hit “Finish” and create the project. However, I recommend that you use the Next button here. Then you’ll see “Active build style” option. A build is a series of compile commands done in the appropriate sequence to create (or re-create) all the related objects in the project. You have three choices. If you want to take advantage of the option to do a build on the sources in your project, then you can either let the tool build a CL program to build the items in your project or you can create your own command to accomplish the build process. Your third option is to say *NONE, which says you don’t plan to take advantage of the ability to do the build. If you don’t do a build, you can still compile the individual source members manually.

I never use the build facility for my projects, so you would think that I normally specify *NONE. But I don’t do that because if I specify *NONE here, then also I lose the ability to push my source changes back to the host from my project, which is a feature that I use constantly! So I typically choose the “Command” option and then specify a CL command that I know does not exist (e.g., dummy as shown in the figure below). That way, even if I were to accidentally request a build at some point, I know it will simply fail rather than do a lot of compiles that I may not want. I find this behavior of removing my “push changes” option when I reject the idea of a build a rather strange quirk of i Projects, but fortunately it’s easy to work around it. Finally, it’s time to “Finish” the project creation.

(Click graphic to enlarge.)

It may seem as if it has taken a long time to create this project, but it’s mostly because of the explanation of the options. I can create a project now in seconds. Next, we need to put some source into the project. There are a couple of different options to do this.

Option 1: Right click on the i Project name and select “Import remote source.” From the resulting dialog, choose the connection to your system, then double-click on “Work with libraries”, and enter the library name associated with this project. When the library name appears, expand it until you see the source file names in that library listed. You can expand any/all source files contain members you want to put into your project. Hold down the Control key and select as many members from one or multiple source files as you need. Don’t worry about selecting the source files themselves, the project will create folders for them automatically. Then click OK. All the source members you selected will be downloaded to your project, along with folders of the names of the source files they belong to. See the figure below.

(Click graphic to enlarge.)

Option 2: Use the Remote Systems view–it’s right below the i Projects Navigator and you’ll probably want to double click at the top of it to make it bigger–to expand the library and source files containing the members you want to put into your project. Hold down the Control key while you select the members you want from one or more source files. Right-click and choose “Add to i Project” and then choose the project you want them to be copied into.

(Click graphic to enlarge.)

You can always add more source members to a project at any time, using any combination of the above techniques. Below a picture of what my project looks like after populating it with both options shown above. Note that I only selected members and the import process created the folders representing the source files automatically.

Remember that you can also create brand new “members” in your project even though it’s not really a member when it’s in the project. It will become a member when you push it back to the host. To create a new one, right-click on the source file name in the project where it belongs and select New→IBM i Source Member (or create a whole new source file if need be). Then put some code into that new source member–feel free to copy some code from other members, either in this project or from other “real” members opened using Remote Systems Explorer.

Especially if you plan to work on this project disconnected from the network (e.g., on an airplane), then I’d advise you to open up the source members and do a Source→Verify action on them, and check your Outline View to make sure all your external file descriptions are populated there. That way, you’ll have all the information cached to be able to verify your code after you’ve made changes without connecting to the host.

Once you have made some changes to some of the code in your project, you can compile individual members, even though you don’t see a Compile menu. Right-click on source member name in the i Projects Navigator, choose “Remote Actions”, and you’ll see the normal compile actions there. It will push your changes back to the host in order to compile the most recent version.

You can also push any changes you have made to code in your project at any time by right-clicking on the project name and choosing “Remote Actions→Push Changes.” I typically do this at least a couple of times a day when I’m doing extensive work in a project just for safe keeping. This copies your changed version of the code back up to the real member in the real source file. You can also push changes for a specific source file or even an individual member the same way. I find it easier to push my changes from the project level so I can’t overlook any.

When your task for which you created the project is complete, you can delete the project exactly how you would expect. Right-click on the project and choose Delete.

There you have it. A quick introduction to creating and using i Projects. Give them a try. You may find that it is a convenient way to organize your work.

Susan Gantner is half of Partner400, a consulting company focused on education on modern programming and database techniques and tools on the IBM i platform. She is also a founding partner in System i Developer, a consortium of System i educators and hosts of the RPG & DB2 Summit conferences. Susan was a programmer for corporations in Atlanta, Georgia, before joining IBM. During her IBM career, she worked in both the Rochester and Toronto labs, providing technical support and education for application developers. Susan left IBM in 1999 to devote more time to teaching and consulting. Together with Jon Paris, she now runs Partner400, and appears regularly at many technical conferences, including System i Developer’s RPG & DB2 Summit. Send your questions or comments for Susan to Ted Holt via the IT Jungle Contact page.