Calling a Sample External Object (RPG)
This document will explain how to create, register, and call a sample External Object written in RPG. Recall from basic training that the purpose of an External Object is to call your back-end business logic directly through an m-Power web application. In this case, the purpose of this External Object will automatically delete all detail lines from an Order Detail table as soon as the parent record is deleted in the Order Header file. If you would like to see similar documentation of this External Object written in different languages, please click one of the following links:
Creating an RPG External Object
Prior to creating an External Object, you must first decide what the purpose of the object will be. As discussed above, the purpose of this External Object is to automatically delete all records from an Order Detail table as soon as the parent record is deleted from the Order Header table. The source code needed to create this object can be found below in two parts:
As you will notice from the code, the CL code will be run first. This code will set the appropriate library list, then automatically call the RPG program. The RPG program will then delete records from the child table based on the parameter passed to it.
Note: Because the RPG program will only be called through the CL program, it is only necessary to register the CL program to m-Power, not the RPG program.
The source code provided above still needs to be compiled. For the sake of this documentation, the CL and RPG code will be located in MRCWORKLIB/RPGLESRC and the files will be named DELDETAILC and DELDETAIL, respectively.
Registering your CL/RPG External Object to m-Power
Open the m-Power interface and navigate to the "Admin Menu". From here, click the "Custom Code" button. Then, navigate to "External Objects" and click the "Create New Object" button. Enter the CL object name of "DELDETAIL", then enter a description that will only be visible by fellow developers. Next select "RPG/CL/COBOL" for the Object type. Lastly, enter the program name of "DELDETAILC" and the program library of "MRCWORKLIB". When complete, your screen should resemble the screenshot listed below:
Once the main program is registered, you will next need to register the necessary parameters. Find the program you just registered and click the "Parameters" icon. Click the "Create Parm" button, then enter in a Parameter Description that will only be visible to fellow developers. Lastly, enter in the parameter length as specified in the CL object. Remember, to map this parameter to your application, you will need a field that has matching attributes. Mark "Yes" for "Required Field". Then press "Accept". When complete, your screen should resemble the screenshot listed below:
The final step of registering your external object is to create the stored procedure that will allow this CL program to be called from a web application. Back on the "Manage External Objects" screen, find the object you just registered and click on the "Plus" icon in the "Stored Procedure" column to create your procedure:
This will pull up the Create Stored Procedure screen where you can view the code used to create the stored procedure, or actually create the stored procedure.
In this case, we want to click the Create button to create the stored procedure for this object. After clicking the Create button, you will see the screen displayed below.
Click Accept to return the Manage External Objects screen.
Calling your CL/RPG External Object within m-Power
Now that you have successfully created the External Object for your CL program and registered it to m-Power, the final step to complete is calling your object at the application level. Since the purpose of this application is to delete records from the child table when the matching record is removed from the parent table, the ideal way to call this object would be from a Maintenance application. The idea here is to let the Maintenance application delete the one parent record, then call your object to delete all necessary child records.
After selecting all necessary fields for your maintenance application, click the "External Objects" icon within the "Optional Specs" column from within the "Application Menu". Select the newly created object from the "Select an object" drop-down. Next, select the After Delete (*AFTERDEL) location from the "Select a Location" drop-down. The reason for using the After Delete location is because we only want the object to be called when a record is deleted from your main application. If a record is added or updated, your application will not be run. Finally, map the correct parameter for the Order #. When complete, your screen should resemble the screenshot listed below:
Compile and run your application. When you delete a record from your Maintenance application, any records that match in your child table (based on the parameter passed to the External Object) will also be deleted.
Notes
- When an External Object is called, your Web application gives all control to the object. Only after the object has completed will control return back to the end-user. For example, if an External Object takes 20 seconds to run, as soon as the user clicks "Accept" to initiate the Object, the user's cursor will turn into a "Waiting" state until the object has finished running. Once completed, the program will finish running.
- External Objects are run in order, based on the External Object locations. External objects called at the same location will be called in the order they were defined to the application. More information about External Object locations can be found here.
- When using this guide to create your own RPG External Object, be sure to replace all references of MRCWORKLIB to your data dictionary and DELDETAIL to your object's name.