Coding Free Format RPG IV April 2010 SEMIUG

Coding Free Format RPG IV April 2010 SEMIUG & MMUG Coding Free Format RPG IV: Jim Martin Author of Free Format RPG IV Copyright Jim Martin 2006 - 2010 1: 1

Coding Free Format RPG IV Power / i aka AS/400, i. Series, System i 5 Coding Free Format RPG IV: Jim Martin Author of Free Format RPG IV Copyright Jim Martin 2006 - 2010 1: 2

Coding Free Format RPG IV Overview • • Free Format – Is it just a new ‘Style’? Introducing Free Format RPG IV What’s new in I/O using free format Program flow – without a Goto! – Logic groups – Proper ‘Ends’ – Call’s • Data manipulation – Eval vs Move – Conversion of decimal, date, & character data types – Must now use the BIFs • Style issues • Problem areas Copyright Jim Martin 2006 - 2010 1: 3

Coding Free Format RPG IV Free Format Is it just a new style? Copyright Jim Martin 2006 - 2010 1: 4

Coding Free Format RPG IV Free Format – Is it just a new ‘Style’? It is the newest ‘style’ – yes. It takes extended factor 2 and makes the space larger, but wait – there’s more! Big changes affect you!!! Here’s a few: No C in column 6 allowed. Must use compiler directive /free to tell the compiler that you are entering the Free-format style. Other compiler directives are OK, such as /Copy. Many fixed format operations are not available, such as Add, Sub, Move. A, Lookup. Some are gone, and some are replaced with Built-in functions Let’s go into detail – in the pages that follow… Copyright Jim Martin 2006 - 2010 1: 5

Coding Free Format RPG IV The free format code block begins with compiler directive /Free (starting in position 7), and ends with /End-free. For example: /Free MPG = miles / gallon; Read File. A; Dow not %eof(File. A); Fieldx = Name; Read File. A; Enddo; Name = %trim(First_N); Invalid_Name = *On; /End-free Copyright Jim Martin 2006 - 2010 1: 6

Coding Free Format RPG IV The free format code block Syntax rules within the free format block: 1. Enter all statements within positions 8 and 80. 2. End all code statements with a semicolon. If a line of code doesn’t fit on one line, just continue on the next line – there is no continuation character, except for character constants. 3. Positions 1 through 5 can be anything. 4. Do not put a C (or anything) in position 6. 5. Do not put a * in position 7 for comments. Comments are placed in the 8 -100 area, beginning with //. You can put a comment after the semi-colon that ended the RPG code. 6. Position 7 can be used for additional compiler directives, such as /copy 7. You must end the free format block to enter embedded SQL. Copyright Jim Martin 2006 - 2010 1: 7

Coding Free Format RPG IV Within the free format block • All 55 (V 5 R 4) supported free format operations are supported, as well as all 76 built-in functions. • The fixed format scheme of level indicators, left hand indicators, defining a field on the fly, and resulting indicators are gone. • The general scheme of coding is: – Op-code Factor 1 Factor 2 • Not all of fixed format’s operations are supported. There are 112 operation codes in fixed format! Many of these are just not needed (ADD, SUB, MULT, etc. ). • Many op codes are implemented via built-in functions. • The generic End statement is gone, you must use the correct End, such as Endif, Enddo, etc. • There is no GOTO operation, so only structured logic can be used, with loop interrupters Leave and Iter. Copyright Jim Martin 2006 - 2010 1: 8

Coding Free Format RPG IV What about “work” variables? • Work variables, if needed, are defined on the D definition specifications – You need many fewer than before. – Longer names for work variables will work out fine – there’s plenty of room. – The notion of expressions, that started with Extended Factor 2, continue with lots of space. – The use of numbered indicators is discouraged; use named indicators instead. Copyright Jim Martin 2006 - 2010 1: 9

Coding Free Format RPG IV Assignment statements Probably the most common free format operation is the assignment statement. An assignment statement is just an Eval statement without the Eval specified. Sometimes you need to put the Eval back in, such as when you want half-adjust in a math expression. Examples: Field 30 = Field 10; Eval(h) Pay = Hourly_Rate * hours; More complex forms: *In 44 = RRN > *zero; // This statement checks for RRN // greater than 0. If it’s true indicator // *In 44 is set on; if it’s false, the // indicator is set off. *In 21 = *In 43 or (Pay > 100); // This statement sets *In 21 to *On // if either *In 43 is *On or Pay > 100. Copyright Jim Martin 2006 - 2010 1: 10

Coding Free Format RPG IV QUIZ ! What happens when you use Eval to add 1 to a 3 digit decimal field that currently contains 999? Have we come to the point in RPG where we do not need any numbered indicators? Is it possible to check a keyed file for the existence of a specific record key without doing a Chain operation? True or False? Free format RPG IV does not need to set *Inlr on to end a program. It’s now automatic. Copyright Jim Martin 2006 - 2010 1: 11

Coding Free Format RPG IV QUIZ ! answers What happens when you use Eval to add 1 to a 3 digit decimal field that currently contains 999? An exception occurs: RNQ 0103 Have we come to the point in RPG where we do not need any numbered indicators? Yes. Is it possible to check a keyed file for the existence of a specific record key without doing a Chain operation? Yes. Use the Setll operation, then use an If with %equal True or False? Free format RPG IV does not need to set *Inlr on to end a program. It’s now automatic. False. We must still set *Inlr on. The cycle lives on. Copyright Jim Martin 2006 - 2010 1: 12

Coding Free Format RPG IV No Klist or Plist – now what? The free format block does not support Klist or Plist, so if you think you need them you will have to code them outside the free format block. The truth is: you don’t need them anyway! The Klist situation is handled by a new scheme to specify the key arguments when using Read. E, Read. PE, Setxx, or Chain. Here’s an example: Chain (arg 1: arg 2) Filex; Isn’t that neat! Another solution exists using a key data structure, which will be shown later. The Plist group isn’t needed either. More details will follow in this presentation, but in reality any program or procedure can be called without a Plist! The method used requires a definition group called a prototype. Copyright Jim Martin 2006 - 2010 1: 13

Coding Free Format RPG IV What’s new in I/O using free format Most I/O functions are the same in free format as they were in fixed format. However, the way you code them follows the syntax of free format. There is no resulting indicator, so you must use %eof or %found, depending on the operation requested. Examples: Read File. A; Dow not %eof(File. A); Write DBRecord; Probably the biggest change is the way we specify key arguments in Read. E, Read. PE, Setxx, and Chain operations, as was shown on the previous page. The key data structure method is shown on the next page. Copyright Jim Martin 2006 - 2010 1: 14

Coding Free Format RPG IV What’s new in I/O using free format Here’s an example of the key data structure method: D Rec_Key DS Like. Rec(File. X: *key) * Let’s assume File. X has key fields Cust. No and Acctno /free Rec_key. Cust. No = Arg_Cust; Rec_key. Acct. No = Arg_Acct; Chain %kds(Rec_key) File. X; If %found(File. X); // process found record here Endif; Copyright Jim Martin 2006 - 2010 1: 15

Coding Free Format RPG IV What’s new in I/O using free format The Update operation was given a third parameter (using BIF %fields) that helps to insure that only specified fields are updated. This has been done for years using exception output and O output specifications, Here’s how you do it: /free Update Record. A %fields(Name: Zip: Amount. Due); The Delete and Exfmt operations are not changed. A small change was made to printer files. You may now specify a named indicator for the OFLIND keyword, instead of numbered ones, or OA-OG and OV. By choosing a name carefully, the program can be less cryptic. Copyright Jim Martin 2006 - 2010 1: 16

Coding Free Format RPG IV Program flow – without a Goto! There are many programmers who have used Goto in RPG programs. In free format calculations, there is no Goto. The experts have said for years that Goto is not a good structured programming method. Doing without a Goto can improve the readability and performance of your programs. Knowing you can’t use Goto forces you to consider other options. Eliminating Goto removes one of the biggest issues in RPG: “spaghetti code. ” Structured program flow is done with the following operations: Dou (Do until) Dow (Do while) If (with Else, Elseif, and Endif) Select (with When, Other, and Endsl) For (with index incrementing up or down) Leave (interrupt logic flow and leave a loop) Iter (interrupt logic flow. skipping to the loop end Copyright Jim Martin 2006 - 2010 1: 17

Coding Free Format RPG IV Proper ‘Ends’ Free format RPG IV does not permit the generic End statement. Every If, Dou, Dow, Select, or For requires the correct Endxx statement. This should be a big help when developing or maintaining a program. The compiler will issue diagnostic messages if you use the wrong Endxx statement in a program. Even this seemingly small detail will help make your programs easier to read and modify. Copyright Jim Martin 2006 - 2010 1: 18

Coding Free Format RPG IV Calls Neither the Call nor Call. B operations are available in free format. And, we previously said that Plists aren’t available either! So, how do we call other programs either dynamically (the old Call) or statically (ILE binding – the Call. B operation)? The answer lies in the Call. P operation. Call. P means Call a prototyped procedure. The Call. P operation references a definition group called a prototype. A keyword on the prototype statement specifies whether the prototype is for an external program (dynamic call) or external procedure (bound call). The prototype defines the parameter list, but there are flexible rules on calling interfaces. Also, similar to the Eval operation, the Callp op code can be omitted when specifying the call. Parameters are passed using a list along with the prototype name. Copyright Jim Martin 2006 - 2010 1: 19

Coding Free Format RPG IV Call example - dynamic D Check_Date D D PR date flag D Yes_or_No Extpgm(‘DATCHK’) 8 0 n S n /free Call. P Check_Date(Screen. Date: Yes_or_No); This is an example of using a prototype to call an external program dynamically. The parameters in the prototype do not need to be named, but any kind of documentation is beneficial. Copyright Jim Martin 2006 - 2010 1: 20

Coding Free Format RPG IV Call example - static D AR 0300 R PR Extproc(‘AR 0300 R’) D Amount 1 5 2 D Amount 2 7 2 /free Call. P AR 0300 R(Screen. Amt: DBAmt); This is an example of using a prototype to call a procedure statically (bound call). Copyright Jim Martin 2006 - 2010 1: 21

Coding Free Format RPG IV Called program A called program using free format will need to have both a prototype and a procedure interface. The parameters specified in the procedure interface will be used in the program. In a recent article, in V 7 R 1, only the procedure interface will be needed in sub-procedures. This will eliminate unnecessary code. Until you get to V 7, continue to code both. Copyright Jim Martin 2006 - 2010 1: 22

Coding Free Format RPG IV Quiz 2 True or False: There was an IBM RPG language before 1965? I can get a remainder in RPG IV without doing a divide operation? How do I check for a run time error in an Eval in RPG IV, since you can’t use the (e) Op code extender? Copyright Jim Martin 2006 - 2010 1: 23

Coding Free Format RPG IV Quiz 2 True or False: There was an IBM RPG language before 1965? True! It was used on 1401, 1410. 1440 I can get a remainder in RPG IV without doing a divide operation? True. Use the %rem BIF. How do I check for a run time error in an Eval in RPG IV, since you can’t use the (e) Op code extender? Use Monitor prior to the Eval, and On-error after the Eval. Copyright Jim Martin 2006 - 2010 1: 24

Coding Free Format RPG IV Data Manipulation Eval vs. Move We all love Move and Movel. We’ve had years to practice using them. So, is Eval the same as Move? The short answer is No. Let’s get acquainted with Eval before going on. Eval blanks or zeroes out the variable on the left side of the equals sign (except for substringing), then copies the item on the right side of the equals sign to it. For numeric fields, decimal alignment occurs. For character fields, left alignment occurs. This makes Eval for character fields equivalent to a MOVEL operation with the Pad option. The Eval. R operation works only with character fields, and is equivalent to a MOVE with the Pad option. Copyright Jim Martin 2006 - 2010 1: 25

Coding Free Format RPG IV Data Manipulation Eval vs. Move (continued) Except for the rare cases where the receiving field is longer than the sending field, and padding is not desired, Eval or Eval. R will do the job nicely. There are two built-in functions that can provide the solution for these rare cases. Consider the substring BIF (%subst) or the replace BIF (%replace) to handle these situations. Copyright Jim Martin 2006 - 2010 1: 26

Coding Free Format RPG IV Conversion of decimal, date, and character A common occurrence is that the wrong data type for the perform. Numeric data comes vice-versa. Dates come into and we need to do some date the data we have is in process we need to to us as characters, or our program as numbers, arithmetic. There are many built-in functions that can solve this situation. Conversion of alpha to numeric can be done with either the %dec or %int BIFs. Conversion from numeric to alpha can be done with the %char BIF. All three of these BIFs can be used to convert a variable of date data type. There are several date formats that can be used to specify an input or output numeric string. Copyright Jim Martin 2006 - 2010 1: 27

Coding Free Format RPG IV Must now use BIFs By now you must have gotten the message: BIFs do a great deal of the work in a free format RPG IV program! In fact, without them the RPG language would be crippled! There are 76 BIFs and only 55 operation codes! This means that we must spend some effort in getting to know the BIFs, in detail. It is just as important as learning the op codes. As with the C language that uses nested functions, we in the new free format RPG world will probably start using more and more nested BIFs to get a desired result. It looks cool, but it can become a maintenance nightmare, since the intermediate work fields generated by the compiler are not debug-able. My suggestion is “no more than 3 deep” in nesting. Copyright Jim Martin 2006 - 2010 1: 28

Coding Free Format RPG IV Style issues There are syntax rules in this free format scheme, and then there are good programming style rules. Style is like beauty, it’s in the eye of the beholder. But some basic rules may help the future readers of your free format RPG program. First, start coding in position 8, not out in the middle. The compiler doesn’t care but your maintenance programmers will. Also, when using logic nesting, using Dow, Select, and If, indent by two spaces for the next level inward. This helps the future reader better see the logic being used. Programmers in other free format languages have been doing this for a long time. Here’s a style issue that may not fly for everyone: Stop using numeric indicators, for anything. You don’t need them anymore. For general logic requirements, create a named indicator in your D definition specs. Pick a name that describes the situation. For example, use Invalid_Acct_Num instead of *IN 45. This removes a level of indirection when someone has to figure out how the program works. Use the file indicator data structure (keyword INDDS) to describe indicators used in display or printer files. Copyright Jim Martin 2006 - 2010 1: 29

Coding Free Format RPG IV Style issues No discussion of style would be complete without mentioning comments. Some people use them, and some people don’t. I am a big advocate of comments. In fixed format RPG we could specify comments on a line by themselves (* in 7), or put comments in positions 81 -100. In free format we have an opportunity to describe line functions on the same line as the operation, but without panning right using the F 8 key. We do this by specifying a // after the semicolon and type away. Be sure not to “parrot” the code. Complete line comments are still useful, and block comments are still needed. Put in all the comments you have time for. Copyright Jim Martin 2006 - 2010 1: 30

Coding Free Format RPG IV Problem Areas Many programmers are still not swayed to try free format because many of their favorite operations are not supported, or convert poorly. The biggest complaints come from programmers who use Move. A a lot. Move. A was created many years ago (RPG II time frame) when there were NO character manipulation operations available. A programmer who needed to inspect or modify a character string moved the string to an array (defined 1 character per element), using the Move. A operation. I did this too. Then the array could be scanned using Lookup, and loop logic could be used to find multiple occurrences of something. The characters could be changed as needed too. At the end of the data handling, the array could be moved back to a field, again using Move. A. Sound familiar? Today we have %scan to find strings; we have %subst and %replace to modify parts of strings; we have concatenation and %trim to put together strings; and we have %xlate to modify selected characters in a string. Conclusion: We don’t need Move. A for character manipulation. Copyright Jim Martin 2006 - 2010 1: 31

Coding Free Format RPG IV Problem areas Using Move. A to move array information to another array is another story. We need to do this sometimes, and the Move. A operation is a great way to do it. So now what? I don’t have a glib response for this situation. But there are ways to do what we need to do in free format, it’s just going to be a bit longer. On the next page is an example of using a based array (using a pointer) to imitate the Move. A operation using the %subarr BIF. Other schemes can be devised, using For loops to get information from one array to another. It’s always possible that IBM will write a new BIF some day that duplicates the Move. A op code. I don’t think I’ll hold my breath on that one. Copyright Jim Martin 2006 - 2010 1: 32

Coding Free Format RPG IV Move. A Example Using the %subarr BIF with a based array to imitate the Move. A operation code: D D D Array 1 Array 2 i Arx S S S 1 Dim(100) 100 Dim(50) 5 U 0 Dim(100) Like(Array 1) Based(Ptr) In the fixed format we could move entire Array 1 into element i of Array 2 by saying: C MOVEA Array 1 Array 2(i) In free format there is no MOVEA, but we can use the based array to overlay an element of Array 2 as follows: Copyright Jim Martin 2006 - 2010 1: 33

Coding Free Format RPG IV Move. A Example continued… Ptr = %addr(Array 2(i)); // Set the pointer to array element Arx = %subarr(Array 1: 1) // This moves the data from Array 1 // to Array 2 element i The based array (Arx) is only a template. It doesn’t have any storage of its own. When the pointer is set above, the template is laid over the 100 bytes of Array 2, element i. The assignment statement modifies those 100 bytes just like the old MOVEA did. Copyright Jim Martin 2006 - 2010 1: 34

Coding Free Format RPG IV So… What do you think? My opinion is that free format RPG IV is here to stay. Every article and example you see in print or on the web uses free format - only. RPG IV is now surprisingly similar to many of the other modern languages of today. It is only a short jump from Extended Factor 2 format to “complete” free format. Now, go do it!!! Copyright Jim Martin 2006 - 2010 1: 35

Coding Free Format RPG IV STOP!!! Copyright Jim Martin 2006 - 2010 1: 36

Coding Free Format RPG IV Copyright Jim Martin 2006 - 2010 1: 37