ILE Essentials, Part 1 Static Binding and Service Programs

ILE Essentials, Part 1 Static Binding and Service Programs Susan Gantner susan.gantner@partner400.com www.partner400.com SystemiDeveloper.com Your partner in IBM i Education In this session, we will take a look at the essential information you need to know about using ILE's static binding to develop modular applications. Using a simple application example, we will illustrate how and why to create modules, bound ILE programs and Service Programs. We will discuss creating modules, bound programs and Service Programs as well as creating and using Binding Directories. Later sessions will focus on maintenance issues related to Service Programs, including Binder Language basics, as well as Activation Groups and scoping for overrides and shared open data paths. The author, Susan Gantner, is co-founder of Partner400, a firm specializing in customized education and mentoring services for System i (AS/400 and iseries) developers. After a 15 year career with IBM, including several years at the Rochester and Toronto laboratories, Susan is now devoted to educating developers on techniques and technologies to extend and modernize their applications and development environments. This is done via on-site custom classes for individual companies as well as conferences and user group events. Jon and Susan author regular technical articles for the IBM publication, IBM Systems Magazine, IBM i edition (formerly iseries Magazine and eserver Magazine, iseries edition), and the companion electronic newsletter, IBM i EXTRA (formerly iseries Extra). You may view articles in current and past issues and/or subscribe to the free newsletter or the magazine at: www.ibmsystemsmag.com/ibmi Susan and Jon are also partners in SystemiDeveloper, a company that hosts the RPG & DB2 Summit conferences. See SystemiDeveloper.com for more details. Feel free to contact the author at: susan.gantner @ partner400.com or visit the Partner400 web site at http://www.partner400.com. This presentation may contain small code examples that are furnished as simple examples to provide an illustration. These examples have not been thoroughly tested under all conditions. We therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. All code examples contained herein are provided to you "as is". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 1-2

What Are the ILE Essentials? The basics (only!) of developing and maintaining ILE applications, including: Creating ILE modules Creating bound Programs Creating Service Programs Maintaining/updating bound Programs and Service Programs Using Binding Directories Using Binder Language Using Activation Groups and Scoping But first of all, why? ILE is about writing in a more modular style Static binding removes potential performance issues from consideration ILE language facilities also allow for a more "natural" form of calling Passing parameters and returning values The topics we cover here will provide a basic overview of the vital information required to develop ILE applications effectively. It gives a foundation for further study into the details of the Integrated Language Environment. ILE is, first and foremost, about writing applications in a more modular style. This involves writing in smaller pieces with little or no call overhead. But it also includes the ability to pass parameters in a more natural function-oriented style with return values, such as RPG's built-in functions. This style of parameter passing is not available with program calls, but only with bound procedure calls. In RPG IV, this is implemented via subprocedures. We will be discussing here how to create and maintain these bound programs. While reusability is certainly not the only goal of modularization, it is one that often provides the biggest "bang for the buck" in beginning our task of modularization. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 3-4

Existing Programs - Duplicated Logic Order Entry Customer Input Customer Search Validate Customer Get next Order # Order Item Entry Validate Product Calculate Item Pricing Calculate Taxes Calculate Shipping Final Order Confirm Submit Order Customer Update Customer Input Customer Search Validate Customer Update Customer Product Update Product Input Validate Product Update Product Order Update Order Input Order Search Validate Order # Customer Input Customer Search Validate Customer Order Item Update Validate Product Calculate Item Pricing Calculate Taxes Calculate Shipping Final Order Confirm Update Order This chart illustrates the simple Order Entry application we will use as our example for modularizing our code using ILE facilities. Notice that many of the functions in each of the (currently) large programs are replicated logic. Modularizing will likely help shrink the overall size of the application while making the application more robust through the reuse of code that has been proven successful in other programs or applications. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 5-6

Modularized Order Entry Program Order Entry Customer Input Customer Search Validate Customer Get next Order # Order Item Entry Validate Product Calculate Item Pricing Calculate Order Taxes Calculate Order Shipping Final Order Total Confirm Submit Order New Order Entry Control flow and Screen I/O Customer Search Get Customer Info Get next Order # Get Product Info Calculate Taxes This chart shows our initial plan for modularizing the Order Entry application. We will take some distinct functions that can be written as server-type procedures which will be called by the Order Entry main module. In addition to making our code reusable within these "green screen" programs, these functions could also serve a valuable role in any future development that may include a GUI or browser-based user interface. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 7-8

Steps From Old to New Separate logic into multiple procedures May put multiple procedures together in same source Subprocedures in RPG Nested programs in COBOL In our example, we'll make each procedure a separate source member Separately compiled Independent modules of code Note that procedures are called with a different syntax from programs CALLB, CALLP or function call in RPG CALLPRC in CL CALL PROCEDURE in COBOL To avoid performance impact of many calls, we'll use ILE's static binding Write & Compile modules separately Bind modules together to create program objects for run time We don't have any silver bullets to offer to help make the task of separating the logic from the older style Order Entry program. The implementation of these new functions, however, is best done as subprocedures for RPG applications or in COBOL applications, more like a small sub-program. In each case the calls from the Order Entry main module will be bound calls, which can mean either a function call from an expression or a CALLP operation from RPG or a CALL PROCEDURE verb from COBOL. If we were calling these procedures from a CLLE (ILE CL) program, the command would be CALLPRC. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 9-10

Bind by Copy Source Mbrs ORDENT ORDENT CRTPGM PGM(ORDENT) MODULE(ORDENT NEXTORD TAXCALC) ORDENT NEXTORD NEXTORD CRTPGM NEXTORD TAXCALC TAXCALC TAXCALC *PGM ORDENT NOTE: Individual puzzle pieces represent *MODULE objects containing procedures of the same name as the module. This chart illustrates the simplest form of static binding, bind by copy. The "compile" step is the CRTxxxMOD step, which creates a *MODULE object. Once all the module objects needed for a program are created, then the modules can be bound together using the CRTPGM command. In this example, all the modules are bound by copy into the program object, ORDENT. This is accomplished by specifying all the modules on the MODULE list parameter in the CRTPGM command. As a result of the CRTPGM command, the program object now contains a COPY of the compiled code that also resides in the module objects. After completion of the CRTPGM command, the module objects may be deleted, if they are no longer needed in any other programs or service programs. After program creation, if changes are needed to any specific module, the module can be re-created and that specific code replaced in the program by using the UPDPGM (update program) command. It is not necessary to re-issue the CRTPGM command to replace a module in a bound program. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 11-12

What About Maintenance? What happens when I need to change the module? e.g., to retrieve different or additional information Simple: Make necessary changes to the source Re-compile the source (into module - ) Update the program to replace the module (UPDPGM) Why not CRTPGM again? More work! Potentially error prone What's the current state of the other module objects? If I need to re-compile, what's the current state of the source? What about other attributes, such as authority, activation group, etc.? Caveat for use of UPDPGM: Does NOT update DSPPGMREF information Could cause problems with some change mgmt, cross reference tools when adding/removing referenced objects Note that even if your change management software or your own use of DSPPGMREF means that you cannot always use UPDPGM or UPDSRVPGM, it can often still be useful in your own working library for unit testing. Before promoting into the system test or production libraries, you may want to consider doing a re-create of the programs to ensure program reference information is correct. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 13-14

Updating a Bound Program Changed Source Mbr ORDENT ORDENT NEXTORD NEXTORD TAXCALC UPDPGM TAXCALC UPDPGM PGM(ORDENT) MODULE() This chart illustrates the effect of UPDPGM. Note that UPDSRVPGM works in the same way to replace a module. The UPDPGM command will also resurface later to help us when maintaining the relationship between programs and Service Programs. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 15-16

What About Re-Use? We COULD create other programs by making additional copies of modules,, Still only 1 copy of the source Still only need to recompile the individual module when changed However, more copies of compiled code means Less efficient e.g. Memory usage More cumbersome to maintain i.e., Need to find and replace ALL copies of a module when changed So, better to put reusable modules in a form where they can be shared more efficiently i.e., a Service Program () object! A big advantage of modular design and ILE is the ability to reuse code. Therefore, a mechanism that allows us the same kind of fast call and function interface that we get with modules bound by copy but shareable among many programs would be nice That's what Service Programs are all about. One copy of the logic shared by many programs that reference the Service Programs. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 17-18

Creating Service Programs, Part 1 CRTSRVPGM CUSTPROCS MODULE( ) EXPORT(*ALL) CRTSRVPGM CRTSRVPGM CUSTPROCS NOTE: If *MODULE objects still exist from earlier step, no need to re-create them here. This chart illustrates creating a service program object. The picture is very similar to the CRTPGM picture we saw earlier for creating a program object with bind by copy. While programs and service programs are created in a similar fashion, how they are used is very different. Service Program objects are never called. They are referenced by *PGM objects. The procedures contained inside a referenced Service Program object, however, can be called by ILE *PGM objects, using a bound call or a procedure call. If a module contained in a service program changes, the old module can be replaced with the new module using the UPDSRVPGM (Update Service Program) command. Note the use of the EXPORT(*ALL) value. This is not the default (as the system comes shipped) for the Export parameter. However, since we have not created Binder Language (a feature we will be discussing a little later) we must use the *ALL option. Otherwise, the binder would look for Binder Language in a source file called QSRVSRC. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 19-20

Creating Service Programs, Part 2 CRTSRVPGM PRODPROCS MODULE() EXPORT(*ALL) CRTSRVPGM CRTSRVPGM PRODPROCS NOTE: If *MODULE objects still exist from earlier step, no need to re-create them here. In our example program, we have decided to create a second Service Program which will contain procedures related to products. While we only have one procedure in the Service Program right now, we anticipate that over time we will add more procedures to the ProdProcs Service Program. Service Programs are typically considered to be packages of multiple procedures. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 21-22

Bind by Copy and by Reference *MODULE ORDENT ORDENT CRTPGM ORDENT MODULE(ORDENT NEXTORD TAXCALC) BNDSRVPGM(CUSTPROCS PRODPROCS) *MODULE NEXTORD ORDENT NEXTORD *MODULE TAXCALC *PGM ORDENT CRTPGM TAXCALC CUSTPROCS PRODPROCS CUSTPROCS References References PRODPROCS This chart illustrates creating a program that references the 2 Service Programs we just created. Note that at least one module must be listed on the Module list of the CRTPGM command and this module will be bound into the program object by copy (that is, it's code will be copied into the program object). The code in the service programs is bound by reference to the program object named ORDENT. Now that the Service Programs are Bound by Reference to *PGM ORDENT, *PGM ORDENT has access to (that is, can call using a bound call statement of some kind) any or all of the procedures in either Service Program. Therefore, this version of the program can perform all the same functions as the Bound by Copy version of ORDENT we created in the earlier example. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 23-24

A Bit Cumbersome... Binding Directories can simplify program creation A Binding Directory (BNDDIR) object provides a search list Used by the binder when looking to resolve an import requirement (e.g., a bound call) Note: The binder will NOT search your library list for objects to include It will only search objects listed on the "Module", the "Bind Service Program" and the "Binding Directory" parameters, if specified First, create a binding directory with the CRTBNDDIR command Then add Binding Directory Entries (AddBndDirE) Or you can "Work With" Binding Directory Entries (WrkBndDirE) Entries are simply the names of the objects the binder may use Names in the entries may be library-qualified 2 types of entries: *MODULE, Do NOT include: Program Entry Modules Modules that exist in Service Programs Listing (or even remembering!) all the modules and Service Programs necessary to re-create a program object can be difficult. For that reason, most ILE developers have found Binding Directories to be very helpful. Using a Binding Directory object, it is not necessary for you to remember or list all the modules and Service Programs on the CRTPGM command. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 25-26

Creating a Binding Directory CRTBNDDIR MYLIB/OEBNDDIR ADDBNDDIRE OEBNDDIR OBJ((NEXTORD *MODULE)) ADDBNDDIRE OEBNDDIR OBJ((TAXCALC *MODULE)) ADDBNDDIRE OEBNDDIR OBJ((ORDINFO *MODULE)) ADDBNDDIRE OEBNDDIR OBJ((CUSTPROCS )) ADDBNDDIRE OEBNDDIR OBJ((PRODPROCS )) ADDBNDDIRE OEBNDDIR OBJ((ORDPROCS )) *BNDDIR OEBNDDIR NEXTORD *MODULE TAXCALC *MODULE ORDINFO *MODULE CUSTPROCS PRODPROCS ORDPROCS Creating binding directories keeps you from always listing commonly used modules and/or service programs on each CRTPGM or CRTSRVPGM. The binding directory will be searched in a similar fashion to the way a library list is searched to resolve other types of references, such as externally described files used by programs or modules at compile time. However, the Binder will NOT go searching your library list for the necessary *MODULEs or s needed to resolve any bound calls you have made in your programs. For that, you must either specify the needed objects or create a Binding Directory object to be used for this search at Bind Time (CRTPGM or CRTSRVPGM). Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 27-28

Using Your Binding Directory CRTPGM ORDENT MODULE(ORDENT) BNDDIR(OEBNDDIR) *MODULE ORDENT ORDENT ORDENT NEXTORD *PGM ORDENT *BNDDIR OEBNDDIR CRTPGM CRTPGM TAXCALC NEXTORD TAXCALC ORDINFO CUSTPROCS PRODPROCS ORDPROCS *MODULE *MODULE *MODULE CUSTPROCS References References PRODPROCS The system binder first copies in all modules listed in MODULE parameter list (ORDENT in this case). Since there is no binding service program listed, any unresolved references must come from the binding directory, if any. An example of an unresolved reference in this case is the bound call to procedure NEXTORD. The binder must find a module or service program containing procedure NEXTORD. The binder finds procedure NEXTORD in a module named NEXTORD, so it copies the procedure into the program to resolve the reference. After copying in procedure NEXTORD, the binder discovers another unresolved reference to TAXCALC and continues to resolve that reference in a similar manner. When an entry is found that matches an unresolved reference, it is copied in if it is a *MODULE or bound by reference (to the service program containing the needed reference) if it is a Service Program. Note that modules or service programs that do not resolve any references are not bound. For example, module ORDINFO and Service Program ORDPROCS, in this case. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 29-30

Better Yet... RPGers can put the Binding Directory parameter in the H spec of the source In this case, most likely on the H spec of ORDENT member H BNDDIR('OEBNDDIR') Then you don't need to specify it on CRTPGM This command will create the same object as on the previous page: CRTPGM ORDENT MODULE(ORDENT) Binding Directories may also be used with the CRTBNDRPG command Only allowed when using DFTACTGRP(*NO) When compiling ORDENT module, you may also bind using: CRTBNDRPG PGM(ORDENT) DFTACTGRP(*NO) If BNDDIR keyword is NOT on H spec in ORDENT, then use: CRTBNDRPG PGM(ORDENT) DFTACTGRP(*NO) BNDDIR(OEBNDDIR) In RPG IV programs, one can list the Binding Directory on the H spec in the program. This is particularly useful because while you are writing the code and referencing a procedure is the best time to include the Binding Directory that will include that procedure. If your shop uses multiple Binding Directories, multiples can be listed, either on the command parameters or on the H spec. Binding Directory can also be used on the CRTBNDRPG or CRTBNDCBL commands, so that you could accomplish binding in combination with a compile of the entry module of the program. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 31-32

And there's more... The basics (only!) of developing and maintaining ILE applications, including: Creating ILE modules Creating bound Programs Creating Service Programs Maintaining/updating bound Programs and Service Programs Using Binding Directories In the appendix here A glossary of commonly used ILE terms Many of these terms we did not cover here, but will in later sessions In other sessions, we'll cover: Using Binder Language Using Activation Groups and Scoping Two additional sessions will cover Binder Language and Activation Groups. This handout includes some additional reference information in the form of a glossary of basic ILE terminology. Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 33-34

Glossary of commonly used ILE Terms Activation group -- This is a logical division within a user's job running one or more ILE programs. It creates an environment within the job designed for ILE programs. Activation groups can be used to compartmentalize the user's job. Within one of these groups, you can create private file overrides that only other programs within that group can see. Of course, overrides that work for all programs in the job can still be done as well. Shared open data paths, ( for example) such as those used by OPNQRYF, and commitment control transactions, can also be made to work either across an entire job or made private to the activation group. Finally, these groups can be used as a method to clean up the user's job. Instead of reclaiming all resources in the job, you can reclaim a specific group of programs. Default Activation Group (DAG) -- This is a special activation group in each job designed specifically for non-ile programs. It's the only part of the job where non-ile programs can run. ILE programs are designed to run in separate ILE activation groups. Service program -- This is a collection of commonly used routines that are written and compiled into ILE modules. These routines don't stand alone, but are always called by and are dependent on programs. The programs are said to reference the service program(s) that contain routines the program needs to call. When a program calls a procedure from a service program, the performance of this action is more like a subroutine call than it is a program call. As a matter of fact, subroutines that contain logic used by multiple programs are a common starting point for service program modules. Original Program Model (OPM) -- This term is used to describe non-ile programs. The system has two program types: ILE programs and OPM programs. For example, programs written in source members without "LE" in the source-member type (RPG, CBL, CL) are OPM programs. For purposes of this discussion (and for most practical purposes), even programs written in RPGLE or CLLE that are compiled with CRTBNDRPG or CRTBNDCL (option 14 in PDM) and use the shipped system default values for the Default Activation Group (DFTACTGRP) parameter value (*YES) are considered to be OPM programs. They behave more like OPM programs than ILE programs. *NEW and *CALLER -- When an ILE program is created, the developer can name a specific activation group where the program should run. Two special values can also be specified for the activation group parameter. *CALLER says the program (or service program) should run in the same activation group with its caller. *NEW says the program should always create a new activation group each time it's called. Activation groups created because of the *NEW attribute on a program are automatically destroyed as soon as that program returns to its caller. Subsequent program calls specifying *NEW result in the creation of a new, separate activation group in the job. Named ILE activation groups, on the other hand, remain in the job and may be continually reused for the same or other programs requesting that activation group name. Program Entry Procedure Module (PEP) - Since ILE programs may contain code from multiple modules, one of the modules must be declared as the one that should get control when the program is called. This is the Program Entry Procedure Module. By default, the first module listed on the CRTPGM command becomes the entry module. There is also a parameter that can be specified to make any module in the list the program entry module. Reclaim Activation Group (RCLACTGRP) command -- This serves a similar purpose for ILE programs to that performed by the Reclaim Resource (RCLRSC) command for non-ile programs. It closes any open files and cleans up the programs' storage in the user's job. Whereas RCLRSC works on all programs in the call stack beyond a certain point in the call stack, RCLACTGRP typically operates only on programs in a specific group. Scope -- As mentioned above, some resources that can be shared between multiple programs in a job, such as file overrides, shared open data paths and commitment control transactions, can be made "private" to the activation group. That means that the override, for example, is only seen by programs in the group where the override command is issued. However, it's also possible for overrides to be issued that are visible across all activation groups in a job. The range of programs that can see one of these shared resources is known as the "override scope," or the "open scope" or "commit scope." Copyright Partner400, 2005-2011. ILE Essentials: Static Binding - Page 35-36