The way companies do business is constantly evolving in response to internal and external changes. For this reason, the software that supports your business environment must also evolve or face obsolescence. The more flexible your software is, especially in areas that are likely to change, the less likely that it will become obsolete.

One area likely to change is the edits that are applied to determine the validity of business transactions. Most of the time, changing the way a value is edited in a program or setting up a new default value involves a simple programming task. When this simple task has to be repeated dozens of times, you might begin to wonder if a better way to derive defaults or edit values exists.

One solution is to avoid duplicating these functions in your programs by encapsulating them in programs or procedures. To make these encapsulated functions even more flexible, you can use a dynamic call that allows a program to wait until runtime to determine which program or procedure is called. Waiting until runtime allows you to change a program’s behavior without recompiling the program.

Throughout this article, I refer to dynamic program calls and dynamic procedure calls. The AS/400 waits until a program or service program is first called to resolve the location of a program or service program’s procedures, even when the program or procedure cannot change without recompiling the calling program. Because the location is resolved at runtime, these types of calls are sometimes referred to as dynamic calls. For the purposes of this article, I use the term dynamic call to indicate that the program or procedure being called is stored in a program variable and can change each time the program is run without recompiling.

You Make the Call

In Original Program Model (OPM) programs, the only way you could wait until runtime to determine which program was called was to store the name of the called program in a program variable. Although you still have this capability in ILE programs, ILE provides you with another alternative: a dynamic procedure call. Dynamic procedure calls let you plug in functions at runtime. Dynamic procedure calls have several advantages compared to dynamic program calls, including better performance, less program initialization overhead, and the ability to use the more flexible, prototyped call interface.

AS/400 programs have always been able to call another program if you’ve placed that program name in a variable. Typically, the calling program retrieves the name of the program being called from a file or data area and uses a variable to call the program using the CALL op code or CALL command. Because the program making the call has no way of knowing which program will be called, information about the program being called is resolved on each call. The system overhead to support this type of call is higher than for any other type of call. Because you might require hundreds of edits to support the validation of a typical business transaction, this type of call can be impractical.

A better-performing alternative to a dynamic program call—the dynamic procedure call—can be made by using a prototype. The prototype allows you to define a return value for a subprocedure. Prototypes also allow parameters to be omitted, passed by value, or passed as constants.

The use of dynamic calls also has some drawbacks. The biggest disadvantage is that most of the documentation and cross-reference tools will not be able to identify and catalog what is being called. For this reason, it is important to document your use of dynamic calls. The other major drawback is that dynamic procedure calls are more complex and require additional steps. Fortunately, you can hide a lot of this additional complexity within subprocedures that encapsulate some of the steps required to support dynamic procedure calls.

Dynamic Procedure Calls

Any subprocedure that can be called using a static procedure call can also be called dynamically using a procedure pointer. Static and dynamic procedure calls have almost identical impact on system overhead, making it practical to use dynamic procedure calls to support call-intensive functions like transaction editing. If you use a prototype to define the interface used for your dynamic procedure call, you can use a return value. Return values allow you to treat the called procedure like a data element, which can make your program easier to understand.

Before you can make a dynamic procedure call, you must have a procedure pointer, which you can retrieve in two ways. The first method employs the %addr built-in function to retrieve the address of the procedure being called. This method requires that the called procedure be defined in the same module as the procedure making the call. (See “Is There an Echo in Here?” MC, August 1999, to learn how this technique works.)

The second method uses APIs to activate the service program containing the procedure being called and to retrieve a pointer to the procedure being called. This is the approach I used in the transaction edit example that follows.

Before you can call a procedure dynamically, you must know the name of the service program that contains the subprocedure. In the example, the service program procedure names are stored in a keyed file. The first time the service program is used, you need to activate it using several APIs. Once the service program is activated, you can retrieve pointers to the service program’s exported procedures and exported data elements using another API.

You activate a service program by calling the Activate Bound Program (QLEACTBNDPGM) API. One of the parameters passed to this API is a system pointer to the service program. I use the C MI library function, Resolve System Pointer (RSLVSP), to set the system pointer passed to the Activate Bound Program API. One of the parameters passed to the RSLVSP API is the hex object type of the service program. Although you could hardcode the hex type for a service program, the example uses the Convert Type (QLICVTTP) API to retrieve the hex type.

To call a subprocedure dynamically, you need to specify a procedure pointer on the prototype for the subprocedure using the EXTPROC keyword. To define a pointer as a procedure pointer, use an asterisk (*) for the data type with the PROCPTR keyword.

Figure 1 contains an example that shows the prototype for a dynamically called subprocedure.

You’ve Found Your Calling

Dynamically called subprocedures have their advantages when you use them to support areas of your applications that change frequently. Areas particularly suited to their use include the retrieval of default field values, validation of field values, support for standard I/O functions, and support for application exit points.

The example I have included shows how you can use dynamic procedure calls to retrieve default values and edit displayed prompt values. The TstDyn program makes dynamic calls to subprocedures contained in the DynCallS service program. These procedures retrieve default values and provide edits for the displayed fields. The names of the subprocedures to call and their associated service program (DynCallS) are stored in files EdtTbl and DftTbl. Each file has a logical built over it, keyed by display file, format, and field. You can download the code and installation instructions for the dynamic edit example using the download link at the Midrange Computing Web site (www.midrangecomputing.com/mc/).

When the DynCall example is first called, it checks to see if any fields that it displays have a dynamically called default value subprocedure. If it detects any, they are called to retrieve the default values. The screen is then displayed. When a user presses Enter, the DynCall program checks for errors by dynamically calling any edit subprocedures for the input-capable fields being displayed. These edit subprocedures validate the data that was entered; if one of them detects an error, it sends an error message and returns an error flag indicating the field in error.

After you download and compile this code, you might want to experiment by adding additional edits to the fields. To do this, copy one of the existing edit subprocedures and give it a new name. You can place this new subprocedure in the DynCall module and service program or create a new module and/or service program. Next, enter the code for your new edit and compile the module and service program that will contain the new edit. After the service program has been compiled, add a record to the EdtTbl file specifying the name of the new subprocedure, service program, display file, format, and field.

You can use the code in this example as a basis for creating a set of subprocedures that support editing of file field values. One area not addressed in this example involves edits that depend upon multiple values. You can deal with this very common situation in several ways. One way you can make related information available to your edit procedure is to post your application field values in a global area that your application and dynamically called subprocedures can access. The local data area (*LDA) is an example of such an area. An alternative that I recommend is to register your program and data file values by name using a subprocedure. I use a subprocedure to store the address of display and data file fields by name in a user index and user space located in library QTEMP.

Last Call

This example demonstrates how dynamic procedure calls allow you to wait until runtime to decide what is called. Waiting until runtime can make it easier to change your applications to fit new requirements. Using this technique, you can even change the behavior of an application as it runs! This technique offers another benefit in that it facilitates the integration and sharing of subprocedures that support commonly used functions into your applications.

Reference

“Is There an Echo in Here?” John V. Thompson, MC, August 1999.

Related Materials

• ILE RPG for AS/400 Programmer’s Guide (SC09-2507-01, CD-ROM QB3AGY01)
• MI Library Reference (SC09-2418-00, CD-ROM QBJADR00)
• OS/400 Object APIs V4R3 (SC41-5865-02, CD-ROM QB3AMQ02)
• OS/400 Program and CL Command APIs V4R3 (SC41-5870-02, QB3AMV02)

**************************************************************************

* DynEdtVal Prototype used to dynamically call subprocedures that *

* edit a field’s value. *

* Input: *

* pFld Pointer to the fields value. *

* Return: *

* RtnErr Error flag indicating field is in error. *

**************************************************************************

DpDynEdtVal S * PROCPTR
DDynEdtVal PR N EXTPROC(pDynEdtVal)
D PR_pFld * VALUE
D PR_DspF 10A CONST
D PR_Fmt 10A CONST
D PR_Fld 10A CONST

...

* Retrieve procedure pointer
C EVAL pDynEdtVal = RtvExpPrcPtr(
C ETSrvPgm:
C ETSubPrc)
* Dynamically call editing sub-procedure.
C EVAL RtnErr = DynEdtVal(pFld: DspF: Fmt: Fld)

Figure 1: Here’s the prototype and dynamic call for the called editing procedure.