Surprises in the New Free Format RPG

Other Declaration Goodies

Since the new file declaration is no longer bound by the 10-character space for file name, you may now use longer names. In this case, of course, you must supply the “real” file name via the ExtFile keyword, in combination with the ExtDesc keyword for externally described files. An example follows to illustrate using these keywords to accomplish this.

So now in much the same way that we provide more meaningful program names on our prototyped calls, we can now do our I/O operations to a file named "CustomerMaster" rather than "OEPFCSTMST" which helps to make our logic more readable.

Named constants can now be used in many more places, such as in place of keyword parameters, including even the length in data declarations. So consider the possibilities of something like the following to make life easier for future maintenance of related fields. Note also the way the capability to modify the length of a variable defined with the Like keyword is implemented for the field InvoiceTotal.

  Dcl-c  CURRENCY_DECS    2;

  Dcl-s  PrintProdCode Packed(PRODCODE_LENGTH);
  Dcl-s  ItemPrice     Zoned( CURRENCY_LENGTH : CURRENCY_DECS);
  Dcl-s  InvoiceTotal  Like( ItemPrice : +2);

Here’s another example where constants can be used to simplify various declarations, especially when combined with the more meaningful file names already mentioned.

  Dcl-f SalesReport Printer OflInd(Overflow)
  Dcl-ds Sales_Report_DS           

Note: At the moment there’s an issue whereby the compiler won’t recognize a constant defined globally for use as a keyword in a subprocedure. But we’re told this will be resolved via PTF.

A great new option for prototypes and procedure interfaces will reduce typing and, perhaps more importantly, the potential typos that often result! It’s the *DclCase (Declared Case) parameter option for the ExtProc keyword. It says that the prototype name as specified—complete with uppercase/lowercase usage—will be used for the ExtProc name. This will be particularly helpful when prototyping APIs with complex case-sensitive names, such as this:

  Dcl-pr Qp0zGetEnvCCSID ExtProc(*DclCase); 
         EnvVar Pointer Value Options(*String); 
         CCSID Int(10) Value;

Things to Watch Out For

Sometimes the surprises can trip you up if you’re not aware of them. So here we’ll point out a few behaviors that are different in the new free format language compared to the way things were before.

Remember that great feature we mentioned where you can use a named constant (or a character variable, for that matter) as a keyword value? That means, however, that in a couple of cases, some interesting compile-time errors can arise.

For example, in fixed format D specs, for both the EXTNAME and DTAARA keywords, the quotes around the name of the file or data area could be omitted. So DTAARA(MyDataArea) in a fixed format D spec refers to a data area object named MYDATAAREA. However, that same syntax in a free format declaration references a character variable or constant named MyDataArea defined elsewhere in the program, which in turn contains the name. So if you want it to work the way it did before you need to add the quotes, i.e., it should be coded as DTAARA(‘MYDATAAREA’). It may be a good idea to consider changing any existing fixed format DTAARA or EXTNAME keywords to use the quoted name syntax—which is equally valid in both fixed and free format—to avoid future confusion.

If you’re fond of using long names that required the use of ellipses (...) on the D spec, be aware that in almost all cases, the ellipses should now be removed. Otherwise, the compiler will try to interpret the code on the next line as part of the variable name. Consider the following examples—all attempting to define a variable named ThisIsALongRPGName.

 Dcl-s  ThisIsALongRPGName...        // Syntax error - Char(10)
                   Char(10);         //  assumed part of name

 Dcl-s  ThisIsALongRPGName Char(10); // This is valid syntax

 Dcl-s  ThisIsALongRPGName    
                   Char(10);         // This is valid syntax

 Dcl-s  ThisIsALong...
         RPGName   Char(10);         // This is valid syntax

Specifying the OVERLAY keyword with a data structure name as the parameter is not supported in free form declarations as it was in fixed format D specs. Instead, you should use the keyword POS(1) to specify starting at position 1 of the data structure. (Note that the use of OVERLAY using a subfield name is still supported as it was in the fixed format.) The following examples show the use of that technique to populate an array with constant data using the old syntax and the new.

    // The old way ...

  D DayData         DS

  D                                9A   Inz('Monday')
  D                                9A   Inz('Tuesday')
  D                                9A   Inz('Sunday')

  D DayArray                       9A   Dim(7) Overlay(DayData)

    // and the new way ...

   Dcl-DS  DayData;

      *N        Char(9) Inz('Monday');
      *N        Char(9) Inz('Tuesday');
      *N        Char(9) Inz('Sunday');

      DayArray  Char(9) Dim(7) Pos(1);


We’re still finding our way with the new free-er format RPG. We’re sure that we’ll develop some new habits enabled by this great new support. And we may even find a few more surprises along the way. If you’ve found surprises that we didn’t list or have developed techniques using the new support, add your comments to our recent blog post related to the free format support.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.

comments powered by Disqus



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters