ILE Activation Groups

Transcription

1 ILE Activation Groups & Binder Language Susan Gantner Your partner in IBM i Education In this session in the ILE Essentials series, we will take a look at the essential information you need to know about using ILEs Binder Language and Activation Groups. This part 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. We will discuss which default parameters to avoid and how to save time and trouble maintaining your code. The author, Susan Gantner, is co-founder of Partner400, a firm specializing in customized education and mentoring services for IBM i (aka, 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: 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: partner400.com or visit the Partner400 web site at 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, Activation Groups & Binder Language - Page 1-2

2 ILE Essentials Developing and maintaining ILE applications, includes: Creating ILE modules Creating bound Programs Creating Service Programs Maintaining/updating bound Programs and Service Programs Using Binding Directories Using Activation Groups and Scoping Using Binder Language 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, Activation Groups & Binder Language - Page 3-4

3 Activation Groups An Activation Group is a division of a job Much like creating "compartments" within the user's job at run time ILE programs specify the group they want to run in Non-ILE programs all run in a special group designed for them Activation Groups have 2 primary features: The ability to scope file overrides, shared open data paths or commitment control transactions privately for the group The ability to clean up (i.e., reclaim) a specific set of programs Rather than the more generic RCLRSC command approach ILE Programs and Service Programs are designed to run in ILE Activation Groups An Activation Group 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. Copyright Partner400, Activation Groups & Binder Language - Page 5-6

4 Activation Groups: An Example JOB Default Activation Group (DAG) Menu Activation Group: ORDENT A 1. Order Entry OE-1 OE-2 OE-3 2. Accounts Receivable Activation Group: ACCTRCV AR-1 AR-2 A This chart illustrates a possible use of application-specific Activation Groups. The order entry application has programs that are designated to run only in the ORDENT activation group. The accounts receivable application has programs that are designated to run only in the ACCTRCV activation group. The 2 applications are called from a menu which is written in an OPM language and is running in the default activation group. (Note: All OPM programs run in the Default Activation Group (sometimes call the DAG). ILE programs typically run in ILE activation groups, but have the ability to run in the default activation group as well. File A is used by both applications. If a set of overrides are required for file A that ONLY apply to the order entry activation group, a new parameter on the OVRxxxF command will allow the programmer to specify those overrides apply only to programs in the ORDENT AG using file A. Likewise, if the order entry application wants to share the Open Data Path for file A, but does NOT want any other (non-order-entry) programs to use the same shared ODP, that can be specified. Commitment control can also be controlled by activation group. Copyright Partner400, Activation Groups & Binder Language - Page 7-8

5 Types of Activation Groups The Default Activation Group - aka, DAG Exists in every job by "Default" Designed for OPM programs - All OPM programs must run here ILE programs may run here, but not recommended Persistent: exists for the life of the job Named (persistent) ILE Activation Groups Named by the programmer Designed for ILE programs & Service Programs Specified when creating programs and Service Programs Persistent: exists until destroyed or end of job Usually destroyed explicitly via API or CL command *NEW (non-persistent) ILE Activation Groups System-provided name when created Specified by programmer by *NEW for ACTGRP NOT persistent: exist only until program creating it ends All jobs start in the Default AG (DAG). In reality, there are 2 Default Activation Groups in a job. One is reserved for system state code and the other is for user application code. In this presentation, when we refer to the Default AG, we are referring to the user application code Default Activation Group (DAG). Named Activation Groups are recommended because of their persistence. Creating and destroying AGs is a very expensive and resource intensive process. Therefore, once an AG exists in a job, it is usually best to leave it there until the programs running there are no longer needed in that job. *NEW has some unique features that make it useful in some limited circumstances. However, its non-persistent nature impacts performance significantly if used often. Since it is the default value for (prior to V5R3) on the CRTPGM command, it is often used unintentionally by default. Copyright Partner400, Activation Groups & Binder Language - Page 9-10

6 Specifying Activation Groups CRTPGM PGM(ORDENT)... ACTGRP(*ENTMOD) CRTBNDRPG PGM(ORDENT)... DFTACTGRP(*NO)... ACTGRP (QILE) ACTGRP options on CRTPGM, CRTBNDxxx commands are: A specific name Program runs in a named persistent ILE activation group QILE is default name with CRTBNDRPG/CBL/CL... not with CRTPGM As of V5R3, QILE Is effectively the CRTPGM default for all except C *PGMs *ENTMOD or *STGMDL(7.1) - CRTPGM Shipped default after V5R2 If entry module is RPG, COBOL or CL, *ENTMOD or *STGMDL = QILE Assuming shipped default of STGMDL(*SNGLVL) in 7.1 If entry module is C, *ENTMOD = *NEW, the pre-v5r3 default for CRTPGM *CALLER Program runs in the Activation Group with its caller *NEW Creates a new non-persistent activation group EVERY TIME the program is called - The shipped default value on CRTPGM prior to V5R3. Often causes performance and functional problems when used by default ** ** ** Note: Only *CALLER or a specific name are available with CRTSRVPGM Prior to V5R3, the shipped default value for Activation Group for RPG, COBOL and CL programs was different depending on how you created the program. If you created the program with CRTPGM, the shipped default for the Activation Group parameter was *NEW. If you created the program with CRTBNDRPG (or CRTBNDCBL or CRTBNDCL), the shipped default for the Activation Group parameter was QILE. On the CRTBNDRPG and CRTBNDCL commands, the Activation Group parameter would only take effect if the developer first changed the value of the Default Activation Group (DFTACTGRP) parameter from the shipped default of *YES to *NO. Note that specifying a name for an activation group only creates an activation group by that name if that group does not already exist in the job. Therefore, it is typically only created on the first call to a program for that Activation Group in the job. *CALLER specifies that the program will run in the same activation group as the program that called it. Note this function even works if the calling program is running the default AG. This is the only way to get an ILE program to run in the DAG. Note that ILE programs running in the DAG is NOT recommended, as we discuss on another chart. *NEW ALWAYS creates a new AG. The system assigns a name to the new AG, which is a number. The *NEW AG is destroyed automatically as soon as the program that created it returns to its caller. This is true even if it doesn't end, e.g., LR is off in RPG or no STOP RUN in COBOL. The new option that was added for V5R3, *ENTMOD, is the new shipped default on CRTPGM. This makes CRTPGM and CRTBNDxxx more consistent in their default behavior. Beginning with 7.1 on CRTBNDxxx commands - the shipped default value for ACTGRP changed to *STGMDL. This means the Activation Group will be QILE as long as the other shipped default for STGMDL(*SNGLVL) is in place. If STGMDL(*TERASPACE) is used, then the Activation Group will be QILETS to accommodate the teraspace model. Check the ILE Concepts Guide (IBM manual) for more information on the teraspace model and its implications for your applications. Copyright Partner400, Activation Groups & Binder Language - Page 11-12

7 What Activation Group to Use? In the beginning, most use the default named AG: QILE If and when a need for scoping or specific program cleanup is discovered, then multiple named AGs may be used *NEW often causes problems Some designs with *NEW work well Many uses of *NEW are NOT by design, but by default It was the default on CRTPGM prior to V5R3 Avoid running ILE programs in the DAG DAG is designed for OPM programs only! Use of *CALLER for *PGMs often causes them to run in DAG Not advised - by IBM and Gantner! Especially when using Service Programs If there are both ILE and OPM programs in the same job, then you have (at least) 2 AGs: QILE (for ILE) and DAG (for OPM) Therefore, you must watch out for scoping parameters More on this coming up Many shops embarking on ILE do not require the resource protection of multiple activation groups for their applications. Using one "generic" activation group name, such as QILE, for all the ILE programs is a good choice in this case, as it is generally not recommended to run ILE programs in the Default Activation Group. And *NEW should not be used for a large number of programs due to performance implications. Changing your CRTPGM command defaults to reflect the name you have chosen is a good idea. Note that if you are V5R3 or later, the default on CRTPGM is already set to QILE for RPG programs, so it does not require change. However, even if you are using QILE or some other generic name for your ILE programs, remember that if you call any OPM programs from the ILE programs, you must still watch out for scoping behaviors for commands such as OVRDBF, OPNDBF, OPNQRYF or STRCMTCTL. Copyright Partner400, Activation Groups & Binder Language - Page 13-14

8 What About Scoping? The scope of a resource determines how many (and which) programs will use it Commonly scoped resources are file overrides, shared open data paths (such as with OPNQRYF), and commitment control transactions There are 3 types of scoping available: Activation Group scoping Resources available ONLY to programs in THIS Activation Group Any shared resources available to all programs in the AG regardless of call stack position Call level scoping "Traditional" OPM-type scoping Overrides, shared ODPs, etc., are used based on program's position in call stack, regardless of Activation Group Job level scoping Resources available throughout the job, regardless of Activation Group or call stack position Call level scoping is what is traditionally used in the Original Program Model (OPM). Note that both Call level and Job level scoping apply to all programs in the job REGARDLESS of Activation Group. In contrast, Activation Group scoping applies to only those programs running in the same Activation Group where the command (override, etc.) was issued. Copyright Partner400, Activation Groups & Binder Language - Page 15-16

9 File Override Scoping *ACTGRPDFN Call level scoping if requested from DAG Activation Group scoping if requested from any ILE AG *CALLLVL Call level scoping for this override *JOB Use job level scoping for this override *ACTGRPDFN OVRxxxF... OVRSCOPE( *JOB ) *CALLLVL The ACTGRPDFN parameter value can be very confusing. Since it is the default for the override and open commands, it is important to understand how it works. Note that the significant factor is what TYPE of Activation Group is the program running when it issues the command: either the OPM default Activation Group (DAG) or an ILE Activation Group, which can be either a named AG (including QILE) or a *NEW AG. Since ILE programs can potentially run in the OPM Default Activation Group (DAG), it is NOT significant what type of program (ILE or OPM) is issuing the command. Rather, where the program is running is the significant point. Note that ACTGRPDFN will issue *CALLLVL overrides ONLY when the override command is issued from the DAG. If the command is issued from any kind of ILE activation group, it will issue *ACTGRP overrides. Overrides can still be combined. Overrides at JOB level are processed last (i.e., overrides any other overrides) In other words, if an override at activation group level says LPI=6 and one at job level says LPI=8, then LPI=8 will be in effect in that Activation Group. Overrides can be merged, just as with call level overrides in OPM today. On this page and subsequent pages with command diagrams, the default values for parameters are indicated with the arrow. Copyright Partner400, Activation Groups & Binder Language - Page 17-18

10 File Open Scoping *ACTGRPDFN Activation Group scoping will be done for shared opens *ACTGRP Only shared within this Activation Group (where command issued) *JOB Use job level scoping *ACTGRPDFN OVRxxxF... OPNSCOPE( *JOB ) *ACTGRPDFN OPNDBF/OPNQRYF...OPNSCOPE( *ACTGRP ) *JOB Note: File opens are only shared if SHARE(*YES) requested regardless of OPNSCOPE use. The OPNSCOPE parameter on the override file commands allows you to specify the scope of the open data path for a file. Note that this will have no effect on sharing of ODPs unless the SHARE(*YES) parameter is also specified on the open or override or on the file itself. Note that the OPNSCOPE parameter specifies which programs in the job will share the SAME shared open data path. Note that even when issued from the DAG, shared open data paths are NOT shared with ILE Activation Groups. This is different behavior from the OVRSCOPE with the ACTGRPDFN value. Copyright Partner400, Activation Groups & Binder Language - Page 19-20

11 Commitment Control Scoping *ACTGRP Commitment definitions scoped to the AG *JOB Commitment definitions scoped to the job *ACTGRP STRCMTCTL... CMTSCOPE( *JOB ) AG1 AG2 PGM A PGM B PGM C PGM D STRCMTCTL... CMTSCOPE(*ACTGRP) OPEN File X Commit(*YES) STRCMTCTL... CMTSCOPE(*ACTGRP) OPEN File X Commit(*YES) CALL B WRITE FILE X CALL C CALL D WRITE FILE X Commit In the example, the commit statement in program D will commit ONLY the record(s) added, updated, or deleted in AG2 -- not the record added while in AG1. The record added in AG1 (in program B) is still uncommitted. This protects applications from one another in a commitment control environment. Copyright Partner400, Activation Groups & Binder Language - Page 21-22

12 What Scoping to Choose? If you want overrides to work as they did before, use OVRSCOPE(*CALLLVL) Recommend that you SPECIFICALLY request it (hard coded) The default ACTGRPDFN may work today, but small changes in the application architecture may change behavior in the future For shared opens, use OPNSCOPE(*JOB) to get as close as possible to OPM behavior Remember to DLTOVR after the function is finished, if necessary For commit, use CMTSCOPE(*JOB) for OPM-style behavior Cannot mix *JOB and *ACTGRP in the same job for commit OVRDBF CUSTMAST OVRSCOPE(*CALLLVL) SHARE(*YES) OPNSCOPE(*JOB) CALL ORDENT DLTOVR CUSTMAST OVRSCOPE(*CALLLVL) Note that we recommend that you specifically request your scoping parameter values - i.e., hard code the value you want. It is more trouble, but it is the safest way to ensure you get the scoping desired and the best way to avoid surprises from the default values. Don't forget that OPNQRYF uses shared opens, so specify OVRSCOPE(*JOB) to be sure that ILE programs in named AGs see the results of the OPNQRYF. Copyright Partner400, Activation Groups & Binder Language - Page 23-24

13 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, Activation Groups & Binder Language - Page 25-26

14 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, Activation Groups & Binder Language - Page 27-28

15 Creating Service Programs CRTSRVPGM CUSTPROCS MODULE(CUSTSCH CUSTINFO) EXPORT(*ALL) CUSTSCH CUSTINFO CRTSRVPGM CUSTINFO CUSTSCH CUSTSCH *SRVPGM CUSTPROCS CRTSRVPGM PRODPROCS MODULE(PRODINFO) EXPORT(*ALL) PRODINFO CRTSRVPGM CRTSRVPGM PRODINFO PRODINFO *SRVPGM PRODPROCS This chart is a review of how we originally created our 2 Service Programs in Part 1. Note that we specified Export(*ALL) each time. This indicates that we are not using Binder Language and the system should generate a signature based on all the callable procedures in the Service Program. Copyright Partner400, Activation Groups & Binder Language - Page 29-30

16 Creating Pgm From Modules & SrvPgms CRTPGM ORDENT MODULE(ORDENT) BNDDIR(OEBNDDIR) *MODULE ORDENT ORDENT ORDENT NEXTORD *PGM ORDENT *BNDDIR OEBNDDIR NEXTORD *MODULE TAXCALC *MODULE ORDINFO *MODULE CUSTPROCS *SRVPGM PRODPROCS *SRVPGM ORDPROCS *SRVPGM CUSTSCH CRTPGM CRTPGM *SRVPGM CUSTPROCS CUSTINFO CUSTSCH CUSTSCH TAXCALC References References *SRVPGM PRODPROCS PRODINFO This chart reviews how we created our program in Part 1, copying in some modules and referencing other procedures by means of referencing the 2 Service Programs. We're using a Binding Directory to make our job easier. 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, Activation Groups & Binder Language - Page 31-32

17 Maintaining Service Programs Earlier we created a Service Program We had to specify EXPORT(*ALL) Because we hadn't yet learned about Binder Language We can make changes to existing procedures - no issue And simply update (or recreate) the Service Program Next time those programs started up, they would use the new version But if we add a new procedure, we need to do more We can either re-bind all the programs using that Service Program OR - We can write Binder Language to prevent the need to do this What happens if we don't do this? All programs referencing that Service Program will fail with a "signature violation" message To avoid this most shops simply use Binder Language So let's look at what it is and why it is necessary Note that signature violations don't happen if you simply make code changes to an existing procedure already in a Service Program. They occur when a new procedure appears in the Service Program - or if one disappears (although removing procedures is rare). Service programs can be updated by using UPDSRVPGM and specifying the module(s) to be replaced. Copyright Partner400, Activation Groups & Binder Language - Page 33-34

18 Service Programs & Signatures Signatures provide interface "level checking" between programs and service programs When a Service Program is created, an export list is created Used at run time to locate the address in the service program for a specific procedure (or exported data item) *PGM records the SRVPGM name and the relative position in the export list for each export used e.g., to call CUSTINFO, branch to address #1 in the SrvPgm's export list Much better performance than searching a list of procedure names The SrvPgm's Signature value is used to check if changes have been made to the export list Bound Call to CUSTINFO 1 2 Export List Address of CUSTINFO Address of CUSTSCH Procedure CUSTSCH *PGM ORDENT Procedure CUSTINFO CUSTINFO: LIBX/CUSTPROCS Export ID 1 Signature 9876 Signature 9876 *SRVPGM CUSTPROCS When Export(*All) is specified, the system binder generates an export list and a signature using an algorithm from the symbol/procedure names in the sequence they are in the export list. If the service program were to be re-created with exactly the same procedures as it had previously, the export list and the signature remain the same. However, changing the list of names in the export list - for example, by adding a new procedure - will change the export list and also the generated signature value. At run time, the *PGM bound to the service program compares the signature saved in the *PGM with the signature of the *SRVPGM. If there is no match, the *PGM activation will fail. By default, this failure occurs during the *PGM startup process - not at the time of the call to a procedure in the service program. If the signatures did not match, ORDENT would need to be re-bound, which would automatically pick up the correct (current) signature from CUSTPROCS. An alternative to rebinding the ORDENT program (and all other programs that reference CUSTPROCS) is to use Binder Language during service program maintenance to manage the signature values. We will look at binder language on the following charts. Please note: The signature values used in this presentation are not realistic. Generated signatures are actually 16 bytes long. They have been greatly simplified here for illustration purposes. Copyright Partner400, Activation Groups & Binder Language - Page 35-36

19 Adding Procedures to a SRVPGM To add new modules to our CUSTPROCS Service Program Create new module(s) (CRTRPGMOD) If previously included module(s) are not still around, re-create them UPDSRVPGM could be used to replace an existing module, but cannot be used to add a new module to the SRVPGM Re-Create SRVPGM CUSTPROCS However - If we specify Export(*All) again The Signature value of the Service Program will change Signature acts as a level-check mechanism for all previously created *PGMs referencing the Service Program Without further action, the ORDENT program would fail with a Signature Violation message What to do??????? The system binder creates a signature with an algorithm from the exported symbol names (typically symbol names are procedure names) and their order. The current signature value of the Service Program is copied into all *PGMs at the time the program is created or updated. Changing the names in the exported procedure list or their order will change the signature in the Service Program. The most common type of change that affects the Service Program's signature is the example here: adding a new procedure to an existing Service Program. If the signature changes, then at run time, the *PGM bound to the service program compares the signature saved in the *PGM with the current signature of the *SRVPGM. If there is no match, the *PGM activation will fail with a Signature Violation message. Copyright Partner400, Activation Groups & Binder Language - Page 37-38

20 Managing Service Program Signatures 2 options are available: 1) Update all programs that reference CUSTPROCS UPDPGM ORDENT MODULE(*NONE) This will update the program with the new SRVPGM signature value Easy now because we only have 1 program referencing it Over time, when many Programs/Service Programs reference it More cumbersome; may be difficult to find which programs to update You could write a program to do it for you If distributing the application to many systems, may still not be a good solution 2) User Binder Language to control SRVPGM Signatures Allows you to request multiple valid signatures be generated Or allows you to hard code a specific signature value So let's look at using Binder Language If the signature values did not match between the *PGM and the *SRVPGM, the program (ORDENT in this case) could be re-bound, which would automatically pick up the new correct (current) signature from FINANCIAL. An alternative to rebinding the ORDENT program (and all other programs that reference the Service Program) is to use Binder Language during service program maintenance to manage the signature values. We will look at binder language on the following charts. Copyright Partner400, Activation Groups & Binder Language - Page 39-40

21 Options for Using Binder Language Three approaches to using Binder Language 1. Let the system generate a new signature after each Export List change Typically you will want to have additional Binder Language to retain all prior signature values in use by *PGMs 2. Hard-code signature values, changing after each Export List change A source of additional documentation rather than a nonsense generated value Still typically uses additional Binder Language to retain all prior signature values in use by *PGMs 3. Hard-code a single signature value, retained indefinitely Simplifies Binder Language required If a mistake is made in Binder Language, could be very tricky to debug Tip: When using this method, archive all previous iterations of Binder Language for help in problem determination Via archiving the earlier source members or commenting out the earlier iterations Third option is the most popular. We'll look at all 3 options so you can decide the best for your shop. The system will generate signatures for your Service Programs if you want. Alternatively, you may specify the value(s) you want to use for signature values. In all cases, the primary reason to use Binder Language is to maintain the signature values that existing programs are expecting. That means that whether you specify the signature value or let the system generate it for you, you will need to make sure that previous signature values are still valid. Otherwise programs looking for those older values will fail when they try to run. Some shops prefer to use a hard-coded value for their signatures even though they plan to change that value each time the export list changes for the Service Program. The signature value can then be used more easily as a source of documentation to show which version of the Service Program is in use. Having a value that is more easily readable than the generated value the system creates makes this feasible. Many (perhaps most) shops choose to create one signature value for the life of the Service Program and keep it the same all the time - or at least for an extensive period of time. Doing it this way does greatly simplify your Binder Language because you are not required to maintain multiple export lists with different signature values. However, this technique could be very difficult to do problem solving on if someone creates the Binder Language incorrectly. Copyright Partner400, Activation Groups & Binder Language - Page 41-42

22 Generated Signature: Step 1 To start, generate the Binder Language for an existing Service Program (before changing it) with RTVBNDSRC RTVBNDSRC SRVPGM(CUSTPROCS) Default source file name: QSRVSRC Default member name: Same as SRVPGM This is just your starting point... Some adjustments I typically make right away: Signature keyword's value is cumbersome (so I delete it) If you omit the keyword, the system will generate the same signature anyway Comments are not likely to be useful in the future (so I delete them) Member CUSTPROCS in QSRVSRC STRPGMEXP PGMLVL(*CURRENT) SIGNATURE(X' D6C351F F3') /******************************************************/ /* *SRVPGM CUSTPROCS PARTNER400 05/21/04 17:54:54 */ /******************************************************/ EXPORT SYMBOL("CUSTSCH") If you don't want to write the Binder Language source for your Service Program by hand, you can use the RTVBNDSRC (Retrieve Binder Source) command, pointing it to your existing Service Program object. Note that this step is done BEFORE the Service Program is re-created to add the new procedure. Notice that if you use RTVBNDSRC, it will include the hard coded signature value. For our simple example, we will be removing the hard coded signature value because we will be creating a new signature value for the new version of the Service Program. The generated code that appears in the lighter font in the example will be deleted. It is not useful for what we're doing here and it can be distracting. Next, make the necessary changes to the Binder Language as you add new procedures to your Service Program. These steps are covered in more detail in the following charts. Of course, since Binder Language is so simple, you may decide to simply key it in yourself from scratch rather than use RTVBNDSRC - especially if you have a fairly small Service Program. Note that the name of the source member and source file containing this Binder Language code is highlighted. The default location for the binder to look for Binder Language is in source file QSRVSRC and in a member named the same as the Service Program. Copyright Partner400, Activation Groups & Binder Language - Page 43-44

23 Generated Signatures: Step 2 Now modify the CUSTPROCS binder language Block copy the entire originally generated source Change second *CURRENT to *PRV Add new procedure name(s) to the END OF the *CURRENT list Each export list generates a new/different signature value That is, each STRPGMEXP Signature value is based on the names of the symbols in that export list STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") STRPGMEXP PGMLVL(*PRV) EXPORT SYMBOL("CUSTSCH") Member CUSTPROCS in QSRVSRC Now that we have the generated Binder Language in our source member, we will begin to make changes to it to prepare for the new procedure. First, for this example, we have decided not to use the hard-coded signature value that the RTVBNDSRC put in. We will let the binder generate the signature values for us. We have also deleted the comments that the RTVBNDSRC command put into the source. That was primarily just to make room on the chart. Feel free to leave the comments in, if you wish. The code we removed before starting is shown in a lighter font. Next, we then took our existing binder language source and block copied it, so that we initially ended up with Binder Language that looked like this: STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL("CUSTSCH") STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL("CUSTSCH") Last, we added the new procedure export to the END of the first list and changed the second list from *CURRENT to *PRV. We may have only one *CURRENT list in the binder language, and it should be the one with the most recent list. Note that the physical sequence of the procedure code in the Service Program (or in the modules) does not need to match the Export sequence in the Binder Language and often will not, as in this case. Copyright Partner400, Activation Groups & Binder Language - Page 45-46

24 Generated Signatures: Step 3 Re-create the CUSTPROCS Service Program This time specify Export(*SRCFILE) - which is the shipped default This "compiles" your Binder Language And creates an export list as specified in the *CURRENT list in binder source This creates a new CUSTPROCS *SRVPGM With 2 valid signature values - one for each STRPGMEXP statement ORDENT (and any other programs that referenced the earlier version of CUSTPROCS) will continue to work with no update required Note: While there are 2 valid signatures, there is still only 1 export list - the *Current one from the binder language source CRTSRVPGM CUSTPROCS MODULE(CUSTSCH CUSTINFO CUSTCHG) EXPORT(*SRCFILE) Export(*ALL) means you are NOT using Binder Language and so the remaining parameters related to source file and member are ignored. Note that when using Export(*All), the export ID list is generated from all the exports in alphabetical sequence. Export(*SRCFILE) means you HAVE created Binder Language and it is located in the source file and member in the latter parameter values. It is important to note the following: Even though you have listed the "exports" in the Binder Language, you must still list the modules to be included in the Service Program in the Module parameter. Sometimes, procedure exports are the same name as the modules. Other times, they are NOT the same. Module name may or may not = Procedure name. In my example, I have only one procedure per module and the procedure names are equivalent to the module object name. But this need not be the case and in many instances will not be the case. Procedure name is what is included in the Binder Language. The sequence of the export ID list - the only list that impacts the Signature of the Service Program - is generated from the Binder Language export list - the one that is marked *Current. It is not impacted by the sequence of modules listed in the module list. Note in this case, the modules are listed in a different sequence from the exports in the Binder Language. The Export List will be generated in the sequence from the *Current export list in the Binder Language. The binder using this binder language will create 2 different signatures -- one corresponding to each list of program exports. Since the list of program exports listed with *PRV is identical to the original version of the service program, the same signature value will be generated for the previous signature as we had in the original version of this service program. Note that even though there are 2 signature values, there is still only 1 export list - i.e., only 1 list of addresses of procedures/exports. For this reason, it is critical that all procedures that were previously in the service program remain in the same relative position in the *Current export list as they were in any/all *Prv export list(s). Copyright Partner400, Activation Groups & Binder Language - Page 47-48

25 Command for Step 3 On the CRTSRVPGM command EXPORT(*ALL) means export all symbols - without Binder Language EXPORT(*SRVPGM) means look for Binder Language Binder Language tells which symbols to export and in what sequence Create Service Program Service program.. CUSTPROCS_ Name Library.....*CURLIB Name, *CURLIB Module > CUSTSCH Name, generic*, *SRVPGM, *ALL Library......*LIBL Name, *LIBL, *CURLIB... > CUSTINFO_ *LIBL + for more values > CUSTCHG_ *LIBL Export *SRCFILE *SRCFILE, *ALL Export source file. QSRVSRC Name, QSRVSRC Library..... *LIBL Name, *LIBL, *CURLIB Export source member *SRVPGM Name, *SRVPGM Export(*ALL) means you are NOT using Binder Language and so the remaining parameters related to source file and member are ignored. Note that when using Export(*All), the export ID list is generated from all the exports in alphabetical sequence. Export(*SRCFILE) means you HAVE created Binder Language and it is located in the source file and member in the latter parameter values. It is important to note the following: Even though you have listed the "exports" in the Binder Language, you must still list the modules to be included in the Service Program in the Module parameter. Sometimes, procedure exports are the same name as the modules. Other times, they are NOT the same. Module name may or may not = Procedure name. In my example, I have only one procedure per module and the procedure names are equivalent to the module object name. But this need not be the case and in many instances will not be the case. Procedure name is what is included in the Binder Language. The sequence of the export ID list - the only list that impacts the Signature of the Service Program - is generated from the Binder Language export list. It is not impacted by the sequence of modules listed in the module list. Note in this case, the modules are listed in a different sequence from the exports in the Binder Language. The Export List will be generated in the sequence from the Binder Language. Copyright Partner400, Activation Groups & Binder Language - Page 49-50

26 SRVPGM with 2 Generated Signatures Member CUSTPROCS in QSRVSRC STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") STRPGMEXP PGMLVL(*PRV) EXPORT SYMBOL("CUSTSCH") Generates Sig Generates Sig *PGM ORDENT Bound Call to CUSTINFO Export List Address of CUSTINFO Address of CUSTSCH Address of CUSTCHG Procedure CUSTSCH Procedure CUSTINFO *PGM NEWONE Bound call to CUSTCHG Procedure CUSTCHG CUSTINFO: LIBX/CUSTPROCS Export ID 1 Signature 9876 Signature 9876 Signature 5678 CUSTCHG: LIBX/CUSTPROCS Export ID 3 Signature 5678 *SRVPGM CUSTPROCS This chart illustrates how 2 signatures work with one Service Program. Note that the original ORDENT program was created before the new module or procedure was added. It has not been updated, so the original signature of the Service Program (9876) is still required for the ORDENT program. However, a new program has been created after the new procedure was added and it is looking for the new current signature (5678). Both programs will find the signature they need and therefore both programs will run without any need to touch the old program(s). Copyright Partner400, Activation Groups & Binder Language - Page 51-52

27 Generated Signatures, Step 4 To add another new procedure in the future Block copy the *CURRENT list Change old *CURRENT value to *PRV Multiple *PRV lists are valid - but only 1 *CURRENT list Always add new procedures to the END of the new *CURRENT list Re-create the Service Program with *SRCFILE as before Now you have 3 valid signatures (still only 1 "real" export list) STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") EXPORT SYMBOL("NEWCUST") STRPGMEXP PGMLVL(*PRV) EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") STRPGMEXP PGMLVL(*PRV) EXPORT SYMBOL("CUSTSCH") Note that it is very important to add any new exports to the end of the export list if you want to maintain previous signatures. You must maintain the same names and sequence of symbols (with the exception of added symbols at the end of the list) as all previous signatures. If done properly, this will allow program previously bound to the service program to continue to run without rebinding. It is EXTREMELY IMPORTANT to understand how Binder Language works before you attempt to use it. If you use it incorrectly, your application will exhibit some bizarre behaviors and the scenario is very difficult to debug. Copyright Partner400, Activation Groups & Binder Language - Page 53-54

28 Hard-Coded Signature Method #1 Hard coded signatures in the Binder Language source Programmer takes RESPONSIBILITY FOR signature values Instead of system generation of signature from export value Still list export symbols, following sequence rules as before Leave previous signatures as is when interface is still valid for all callers or change it if you want to force re-bind STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('CUSTPROCS19MAR06') EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") EXPORT SYMBOL("NEWCUST") STRPGMEXP PGMLVL(*PRV) SIGNATURE('CUSTPROCS15JAN06') EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") STRPGMEXP PGMLVL(*PRV) SIGNATURE('CUSTPROCS03SEP05') EXPORT SYMBOL("CUSTSCH") Our earlier examples of Binder Language used the default behavior of letting the system generate it's own signatures from the exports in each of the STRPGMEXP... blocks. Another alternative is to "hard code" your own signature values in the STRPGMEXP statement. This is illustrated in this example. It is important to remember that you must still maintain all old signatures that may be out there in programs. You must also still remember to keep the old procedures in the same relative positions in the list to any and all previous signatures. The only major advantage of this example is that the signature(s), which can be seen with the DSPSRVPGM command give us some additional information about the history of the service program and its updates. Use hard-coded signatures very carefully. Hard coded signature values are quite workable, as long as you still adhere to the rules on the following chart on adding or changing the exports of a Service Program. Copyright Partner400, Activation Groups & Binder Language - Page 55-56

29 Hard-Coded Signature Method #2 You may choose to keep the signature the same EVEN IF the export list has changed Still add new procedures ONLY to the END of the list Change it if/when you ever decided to force a re-bind Less cumbersome Binder Language STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('CUSTPROCS') EXPORT SYMBOL("CUSTSCH") Member CUSTPROCS on 1st CRTSRVPGM STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('CUSTPROCS') EXPORT SYMBOL("CUSTSCH") Member CUSTPROCS on 2nd CRTSRVPGM EXPORT SYMBOL("CUSTCHG") STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('CUSTPROCS') EXPORT SYMBOL("CUSTSCH") EXPORT SYMBOL("CUSTCHG") Member CUSTPROCS on 3rd CRTSRVPGM EXPORT SYMBOL("NEWCUST") This is another example of using hard-coded signature values. Notice that in the previous examples, we continually added STRPGMEXP... blocks for each new procedure as it was added to the Service Program. This continually added signature values which, ultimately someday, will likely need to be cleaned up. When using hard coded signatures, you do not necessarily need to have multiple export lists and multiple signature values. You could maintain only one list whose signature value stays the same even though the list of exports in the list keeps growing -- as long as all new exports are added to the end of the list and none are taken away or resequenced. This is illustrated in the three versions of binder language below for the Financial Service Program. Each time we add a new procedure to the SrvPgm, we add the new name to the END of the one list of program exports in the Binder Language. The difference here is that we keep a single STRPGMEXP... block all the time in the Binder Language source. We don't keep adding new blocks and we don't add new signatures each time. In this case, we keep the signature the same all the time, so all old and new programs work because all are looking for the same signature value. PLEASE NOTE: It is EVEN MORE IMPORTANT in this example that the old procedures remain in their original positions in the program export block. In this case, since there is only one STRPGMEXP... block all the time, it will be very difficult to do problem determination on what went wrong if someone resequences the exports in the block or omits an export by mistake. This alternative makes for easier coding, but far more difficult problem determination in the event of somone creating incorrect Binder Language. Tip: When using this method of Binder Language, you should still maintain the older versions of the Binder Language (either archive the source members or comment out the older ones in one source member). That way, if something does go wrong, the historical record of the earlier versions of the Binder Language may help you figure out where the Binder Language went wrong. Copyright Partner400, Activation Groups & Binder Language - Page 57-58

30 Binder Language Rules We have only covered the basics of Binder Language here Other things can be done with Binder Language Beyond the scope of this session Tips for changing the export list: Always: Add new exports to the END of the export list Export list sequence IS the sequence of exports in Binder Language for *CURRENT Avoid removing exports from a service program If you must remove an export and you want to retain use of a previous signature Put in a place holder for the export you remove WATCH OUT! If you have any *PGMs bound to this SRVPGM using that export, they will have unpredictable results! Probably best overall to re-bind (UPDPGM) all programs that reference the Service Program if a procedure is removed In this case, clear all *PRV lists in the Binder Language It is critical to maintain the sequence of all *PRV exports in the *CURRENT list Note that you are not REQUIRED to use Binder Language. If you prefer, remember that you may, as an alternative, re-bind (using UPDPGM command) all the *PGMs that reference the *SRVPGM that has changed. It would be best to do this using a program. If you want to write your own program to do this, you may want to look at a sample of how such a program might work in an article from the IBM Systems Magazine EXTRA newsletter at: Copyright Partner400, Activation Groups & Binder Language - Page 59-60

31 Example of Doing it WRONG Member CUSTPROCS in QSRVSRC STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL("CUSTCHG") EXPORT SYMBOL("CUSTSCH") STRPGMEXP PGMLVL(*PRV) EXPORT SYMBOL("CUSTSCH") Did NOT add new proc at end of list CUSTINFO is now in seq 2 Old list has CUSTINFO in seq 1 *PGM ORDENT *PGM NEWONE Bound Call to CUSTINFO Pointer to CUSTCHG Pointer to CUSTINFO Pointer to CUSTSCH Procedure CUSTSCH Procedure CUSTINFO Bound call to CUSTCHG Procedure CUSTCHG CUSTINFO: LIBX/CUSTPROCS Export ID 1 Signature 9876 Signature 9876 Signature 5678 *SRVPGM CUSTPROCS CUSTCHG: LIBX/CUSTPROCS Export ID 1 Signature 5678 What's wrong with this Binder Language? The current signature did NOT maintain the sequence of the original (*PRV) signature. In this scenario, program ORDENT will run, but it will call procedure CUSTCHG (the one in export position 1) when it was supposed to call procedure CUSTINFO (the one that was on position 1 when the *PGM was originally created, but is now in position 2). Note that this mis-sequencing would be a problem no matter which of the 3 options we use for getting the signature value. Copyright Partner400, Activation Groups & Binder Language - Page 61-62

32 Make it Easier to Do it Right Suggest adding comments to Binder Language Reiterating the rules for those who may forget Thanks to Barbara Morris from IBM for this idea... AND... archive older versions of binder language with each change /*=========================================================*/ /* Even though the list might seem to have some order, */ /* new exports MUST be added at the end. */ /*!!! The order MUST NEVER CHANGE!!! */ /*=========================================================*/ STRPGMEXP PGMLVL( *CURRENT ) SIGNATURE('MYSIGNATURE') EXPORT SYMBOL( "PROCEDUREX" ) /* 1st symbol in list - do not change */ EXPORT SYMBOL( "PROCEDUREY") /* 2nd symbol in list - do not change */ EXPORT SYMBOL( "PROCEDUREZ" ) /* 3rd symbol in list - do not change */ /* Add new exports below last EXPORT SYMBOL */ This idea from IBM compiler architect, Barbara Morris, gave us this idea of documenting the basic rules of binder language into the source via comments to help ensure that anyone making changes to it understands the basic rules. This does not replace the idea of archiving the older versions of the binder language when changes are made - just in case someone makes a mistake even with the comments in place to help prevent it! Copyright Partner400, Activation Groups & Binder Language - Page 63-64

33 Whew! We've covered a lot of ground Modularizing program source Creating and maintaining bound ILE programs Creating and maintaining Service Programs Creating and using Binding Directories Using Binder Language Using Activation Groups and Scoping of job resources We have ONLY covered the essentials here There is much more to understand about taking full advantage of ILE Resources are listed on the next page for you to continue learning about Activation Groups and Binder Language To learn more, try these resources Susan Gantner The Seven Deadly Sins of ILE Commonly Asked Questions about Activation Groups Scott Klement Binder Language and the Signature Debate iprodeveloper.com/article/rpg-programming/binder-language-and-the-signature-debate A Beginner's Tour of Activation Groups iprodeveloper.com/article/rpg-programming/a-beginners-tour-of-activation-groups-509 ILE Concepts Guide pic.dhe.ibm.com/infocenter/iseries/v6r1m0/topic/books/sc pdf Who Knew You Could Do That with RPG IV? Copyright Partner400, Activation Groups & Binder Language - Page 65-66

34 The 7 Deadly Sins of ILE 1. Run ILE programs in the Default ILE Activation Group (DAG) Use ILE named Activation Groups instead (such as QILE) 2. Run Service Programs in the DAG Can be an even bigger problem than #1 3. Use *NEW by default, rather than by design Until V5R3, *NEW was the default on the CRTPGM command 4. Using *CALLER as the default Activation Group value Tends to cause problem #1 if you're not careful 5. Failure to use RCLACTGRP only when necessary 5b. Using RCLACTGRP(*ELIGIBLE) in production code at all 6. Allow scoping parameters to default to system-shipped defaults 7. Use of the RCLRSC command Its impact is variable depending on where used and on what type of programs This chart represents some of the common practices in ILE applications that have caused many shops problems. While none of these practices will necessarily have serious consequences for all applications, all of them have the potential to cause headaches eventually. Many shops find they can successfully break some of these rules and still have few, if any, serious problems. In that sense, it's probably overly dramatic to refer to these as "deadly sins". Our point here is simply to point out practices that can and have caused problems for many shops. All of them can be avoided fairly simply. We don't have room here to go into detailed explanations about all of these practices and how and why to avoid them in this handout. We have covered many of these points elsewhere in the presentation. For a more in-depth explanation of these specific practices, read our article for the i5 EXTRA electronic newsletter for April 2004 entitled "The Seven Deadly Sins of ILE". Copyright Partner400, Activation Groups & Binder Language - Page 67-68