Create Your Own Compile Commands in WDSC

August 4, 2004 Bruce Guetzkow and Kushal Munir

The code for this article is available for download.

If you have been using IBM‘s application development tool, WebSphere Development Studio client for iSeries, you have probably been using it for everyday development of RPG and COBOL applications. WDSc lets users customize many aspects of development, such as the ability to create or modify compile commands. This article looks at how you can create your own compile commands in WDSc to invoke commands on the iSeries, and retrieve the results of compiles in the iSeries Error List view.

We begin with a brief overview of how compile commands work in WDSc. Compile commands are associated with a source type and are identified with a label. For RPGLE members, for example, IBM ships the default compile labels Create Bound RPG (CRTBNDRPG) and Create RPG Module (CRTRPGMOD), which execute the commands CRTBNDRPG and CRTRPGMOD respectively. Users can also change or add compile commands associated with a member type. In the Remote Systems view in WDSc, users can right-click a member and select Compile, Work With Compile Commands. This brings up the Work With Compile Commands dialog (see Figure 1). The dialog allows users to pick a member type and add or modify the compile commands associated with it. For example, Figure 1 shows a new compile command labeled My command, associated with an RPGLE member type, which actually executes the command CRTBNDRPG. The label is what the user sees in the Compile and Compile (Prompt) menus when right-clicking a member of that type. It is simply an identifier. The actual command executed is the one specified in the Command field of the dialog. Note the substitution variables used in the command. These are similar to PDM substitution parameters (for example, &L is replaced by the library name, and &N is replaced by the name of the selected member).

Figure 1: The Work With Compile Commands dialog in WDSc

When an IBM compile command, such as CRTRPGMOD or CRTBNDRPG, is executed, the compiler produces an events file, which contains the results of the compile. Once the command has completed, WDSc retrieves the events file, parses the results, and shows them in the iSeries Error List view. Users are then able to double-click the errors in the view to open them in the LPEX editor. To execute your own host command and retrieve events files for them, your command must satisfy two requirements. It must have the SRCMBR(. . .) parameter. It must also have the OPTION(*EVENTF) parameter.

If your command calls an IBM compile command explicitly, ensure that the IBM command is called with the OPTION(*EVENTF) parameter. Note that some IBM compile commands, such as CRTPGM and CRTSRVPGM, do not allow this parameter, since they don’t produce events files.

If your command does not issue an IBM compile command explicitly, but instead uses QCMDEXC to execute an IBM compile command, there is an extra set of steps to go through (in addition to the two requirements above). In this case, you also would have to write the events file location to the local data area for WDSc in order to retrieve the events file. This is done by writing the library name to the first 10 bytes and the member name to the next 10 bytes of the local data area. If the library name or member name is less than 10 characters, pad the remaining bytes with spaces. Note that IBM commands produce events files in the target library (that is, the library where the program or module would be created), in a special file called EVFEVENT. The events file member name is the same name as the member being compiled.

The above instructions will also work if your command uses QCMDEXC to call an IBM command that does not produce an events file (CRTPGM, for example). How is the events file produced in this case? You would write one yourself. The events file format is a published “standard” and is documented in WDSc’s Help (go to the Help menu, then Help Contents). From the Help window, select iSeries application developer information, CODE, Editor, Tips and Techniques, Using CODE Editor, Events File Information, then Events File Format.

CREATING YOUR OWN EVENTS FILE

Service program EVENTSFILE (EVENTSFILE_SQLRPGLE.txt and (EVENTSFILE_CPY.txt) contains procedures that you can use to create your own events file. To simplify how the file is created, all errors, when selected from the iSeries Error List view, will appear at the top of the source member.

The procedures should be used in the following order:

The #crtevtfilembr creates and clears the events file member. Parameters are Object Library, Source Library, Source File, and Source Member. This procedure should be called once for the source member being compiled.

The #wrtevtfileerror writes a record for each error you want to appear in the error list. Parameters are Message ID and Message Text. This procedure should be called optionally for each error message to be reported.

The #wrtevtfilefileend writes a record indicating that the events file is at an end. There are no parameters for this procedure. This procedure should be called at the end of your compile command processing program.

A NEW COMPILE COMMMAND

Now that you’ve seen what is required to return errors to the iSeries Error List window, here is an example of a command that does just that. The Create Module (CRTMOD) command is a simple front-end to the Create CLLE Module (CRTCLMOD), Create RPG Module (CRTRPGMOD), and Create SQL RPG (CRTSQLRPGI) commands. The command has four parameters:

Module specifies the name of the *MODULE object you wish to create.

Source File specifies the source file that contains the member you wish to compile.

Source Member specifies the member to be compiled (or *MODULE, to indicate that the member name is the same as the module name).

Option indicates whether you wish to create an events file.

The critical parameters are the Source Member (SRCMBR) and Option (OPTION) parameters. These parameters must exist on your command for this to function correctly. (The source for the command is in (CRTMOD_CMD.txt.)

The command processing program CLLE source member (also CRTMOD) is very simple. It begins by parsing the MODULE parameter into name and library components. The same is then done for the SRCFILE parameter. If *MODULE is specified for the SRCMBR parameter, it is replaced with the module name.

The Retrieve Member Description (RTVMBRD) command is then executed to determine the source member type. If any errors occur, a generic error message is sent back to the user and the program ends.

The next section executes a compile command based on the member type. The compile commands use the parameters specified on the CRTMOD command, along with any other parameters specific to the developer’s installation. If the parameters shown do not match your requirements, you will need to update accordingly. If the source member type is not CLLE, RPGLE or SQLRPGLE, an error message is returned to the developer. (The source for the command processing program is in CRTMOD_CLLE.txt.)

TRY IT FOR YOURSELF

Now that you’ve seen how WDSc handles compile commands, you should be able to custom tailor any compile command to meet your needs.

Bruce Guetzkow has programmed on the AS/400 and iSeries since 1990, in manufacturing, distribution, and other industries. He is currently the IS director at United Credit Service in Elkhorn, Wisconsin. E-mail: bguetzkow@itjungle.com

Kushal Munir is a software developer at the IBM Toronto Lab, Canada. He has been a member of the WDSc team since 2001. E-mail: kmunir@ca.ibm.com