Wednesday, February 12, 2014

File definition in RPG all free

rpg free file sepecification dcl-f tr7

While I have been working with the new RPG all free (released in November 2013) I have unable to find examples comparing the pre-change to the post-change RPG code. Therefore, I thought I would give some examples of how to define files here.

When I first heard that RPG had gone completely free I was concerned that we could now intermix everything. This scared me as I had vision of people intermixing file definitions with the equivalent of calculations, etc. Fortunately what I have found is while you can intermix the new definition statements, you cannot insert them into the equivalent of the "calculation specifications".

In the move to RPG all free the following specifications have been replaced:

  • Control (header) specifications with ctl-opt
  • File specifications with dcl-f
  • Definition specifications with dcl-s and dcl-ds
  • Procedure specifications with dcl-pr, dcl-pi, dcl-proc, end-proc
  • Input and Output specifications remain in fixed format, I think this is a big hint from IBM that we should no longer be using these specifications.

At the time I am writing this post to be able to use the RPG all free your IBM i server needs to be running 7.1 and have PTF SI51094, or a later superseding PTF, loaded. If you do not know if you have this PTF loaded read How to tell if you have the PTF for RPG all free.

What I am going to do is give an example of a File specification and then its equivalent in free. I am not going to cover every possibility of how to define a file, these are the most common ways I define files.

All file definitions start the declare file word, dcl-f, and end with a semicolon, ;. I have found that it is not truly free format. There are certain keywords that must occur before other. If you get a compile or syntax errors try rearranging the keywords.

The first example is very simple, a data file is being defined as input and without a key. As this as this is a data file I would use the disk keyword. There is now a usage keyword that defines how the file is used, which in this example is just for input.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    IF   E             DISK

       dcl-f TESTPF disk usage(*input) ;

Both the disk and usage(*input) are optional. I could code the file without them and they are assumed.

       dcl-f TESTPF ;

Now let’s make this a bit more complicated. In this example I still only want the file for input, I want to access the file as keyed so I use the keyed keyword, and I am going to use the prefix keyword. Notice how I have also not used the disk keyword.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    IF   E           K DISK    prefix(a_)   

       dcl-f TESTPF usage(*input) keyed prefix(a_) ;

Now I want to update the file so the usage becomes *update, and to rename the record format I am using the rename keyword that was available pre-TR7. Notice how the dcl-f code now takes two lines.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    UF   E           K DISK    rename(TESTPFR:NEWNAME)

       dcl-f TESTPF usage(*update) keyed                        
                         rename(TESTPFR:NEWNAME) ;              

Having used a file for input and update what about for just output, usage is *output.

Why do I do that? Even though the file itself is keyed no-one has ever given me a good reason to define a file in a RPG program as keyed if I am just writing to it.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    O    E             DISK

       dcl-f TESTPF usage(*output) ; 

If I have a file that I want to read (input) and write to (output), without updates, I would code the usage for both *input and *output. Notice how they are separated with a colon, :.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    IF A E           K DISK

       dcl-f TESTPF usage(*input:*output) keyed ; 

In this example I want to be able to read (input), write to (output), without update. The usage would just be coded for *update and *output, it assumes that input is needed as part of the update.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    UF A E           K DISK
 
       dcl-f TESTPF keyed usage(*update:*output) ;

There is one addition to the new, a new type of usage. If you want to delete records from a file its usage must include *delete. In this example I want to read (input) from the file and then delete records. I do not have to give *input as that is assumed with the *delete.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    UF   E           K DISK

    dcl-f TESTPF keyed usage(*delete) ;

And what about an update with write (output) and delete.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPF    UF A E           K DISK

    dcl-f TESTPF keyed usage(*update:*output:*delete) ;

After data files, physical files, logical files, SQL tables and SQL indexes, the next most common type of file I use is a printer file. As this is not a disk file I do have to give the file type, printer.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTPRTF  O    E             PRINTER
       dcl-f TESTPRTF printer ; 

As with printer files I have to give the file type for a display file. As I am using the display file for both input and output I do not have to give the usage as input and output is assumed. I have also used the indicator data structure keyword, indds, and as the display contains a subfile the sfile keyword.

   FFilename++IPEASF.....L.....A.Device+.Keywords
   FTESTDSPF  CF   E             WORKSTN indds(IndDs)
   F                                       sfile(SFL01:Z1RRN)

       dcl-f TESTDPSF workstn indds(IndDs) sfile(SFL01:Z1RRN) ;

I know that the above examples do not cover every type of file and scenario. I hope that this gives you a good basis of how to code the dcl-f in your own work.

You can use PDM for coding RPG all free, I did for this post to show that it was possible. Before you do you need to turn the syntax checking off. I explained how to do so in the post TR7 available today.

 

You should read my other posts introducing all free RPG:

32 comments:

  1. Nice examples Simon. One thing to consider: Cross reference tool vendors (Abstract, Hawkeye, Total, etc) may not be ready to consume the new format yet. Making programs in fully free RPG may make them unknown to your cross reference tool.

    ReplyDelete
  2. Very good, I am still waiting for us to install the update so I can play with the new world.

    ReplyDelete
  3. When you create a new source member in PDM, are you specifying a type of RPGLE and using CRTBNDPGM to compile it, like we did on the "old" RPG Free code? Or do you use something different?

    ReplyDelete
    Replies
    1. If you have the PTF then you are correct.

      Source type is RPGLE and you can use CRTBNDRPGM to create the program object.

      Delete
    2. Joe, the new fully free RPG is exactly the same as the /free RPG you are already using. The same source member type, the same compiler commands, everything. The only difference is that you don't need to write /free any more, and if you want to, you can use DCL-F and friends instead of F specs et al. But be advised: SEU will never understand fully free RPG, and will throw a syntax error on every line you write. SEU is frozen at 6.1. Use RDi instead; it already supports the new syntax quite nicely.

      Delete
  4. "I have found that it is not truly free format. There are certain keywords that must occur before other. If you get a compile or syntax errors try rearranging the keywords."

    Really? That's your definition of "free format"? Then there is very little about ANY language that is "truly free format". Every statement in EVERY language - whether it be C++ or RPG all free has that requirement - I triple dog dare you to put the following:

    NOT %EOF(SPYVIEW) DOW;

    After all - it's not "truly free format" unless you can put the keywords in any order. The above should work.

    ReplyDelete
  5. On February 19th Lisug(Long Island Systems Users Group) is holding a meeting with two educational sessions. The first being a live demo of Open Access and the second being File I/O with data structures. The same as demonstrated in the above article. This is being held at the Fox Hollow Inn in Woodbury, NY.

    ReplyDelete
  6. At first I was a bit skeptical of additional free format RPG specs. I've embraced free-format calc specs since first available - no love lost for fixed format c-specs. But Jon Paris writes a compelling argument for going all "free". See: http://www.itjungle.com/fhg/fhg021214-story01.html

    ReplyDelete
  7. I have started using it recently and am really impressed with it. The code looks so clean. I am liking it.

    ReplyDelete
  8. Thanks for sharing the way as how to go for it, One question, is it possible to intermix spec, like I define a file in between calculation spec's.

    ReplyDelete
    Replies
    1. No. You cannot intermix the new definitions amongst "calculation specs".

      In my opinion that is a good thing. I hate to think of the chaotic/unstructured code that some people would create.

      Delete
  9. I've been thinking that refering to the new version of RPG either as "IV" (which it has progress far past) or "totally free" or "all free" is really doing this version a disservice.

    I propose we start a grassroots movement if IBM won't recognize the importance of this advancement and start calling it "RPG V" on our own.

    What do you think?

    ReplyDelete
    Replies
    1. I agree with you this enhancement makes it so much more than RPG IV.

      In a Facebook group I am member of we had a discussion about this. The best name we came up with (apart from the "clever'/"funny" ones) was "RPG i".

      Delete
  10. Many examples in the version of the manual that is in RDi 9 help - there is a separate section just for free-format. Half a dozen "Free format equivalent for..." sections, lots of examples of everything you can do.

    I wish that InfoCenter had this - the 7.1 InfoCenter DOES have the "update" ILE RPG Reference, which includes free-format documentation, albeit rather scattered throughout the document. The RDi version is much easier to get at what you want to know, IMO.

    ReplyDelete
  11. Thanks, Simon. I did not know RPG had progressed this far. I'm an enthusiastic author of rpg /free for calcs for years, but never knew all the other specs can be modernized as well until I saw your examples. Do you know what RDi is and how to access it as a replacement for SEU - as referred to by Buck above?

    ReplyDelete
    Replies
    1. You can download a trial of RDi from IBM's website here.

      (I cannot make a link open in a new window from a comment, so right click on the link and select "open in new tab" to keep this post open)

      Delete
  12. Per your request on Linked In, I wanted to post my comment here as well:

    We recently did a Webinar with Barbara Morris (last week in fact), and covered this topic. You may find what we discussed to be useful:

    http://bit.ly/1fkDZUO

    ReplyDelete
  13. When I am declaring a file with DCL-F filename. The line is highlighted in reverse image and error message is something related to EVAL. Is it a known problem for free format file. My program type is RPGLE. While C spec operations in free format are working fine. Can you please advice what to do in this situation. My AS400 version is V7R2.

    ReplyDelete
    Replies
    1. Are you using PDM/SEU?

      If so it does not support syntax checking for IBM i 7.1 and beyond.

      What you need to do is to turn off syntax checking in SEU. This post describes how to do it here.

      Delete
    2. Thank you very much for Reply. Will try this option under change default settings.

      Delete
  14. Hi Simon,
    Great article ! Can you please also let us know, how to define a program described and primary files in RPG all free..

    ReplyDelete
    Replies
    1. Neither the Input nor the Output specification has been converted to free format. The Input specs go after the DCL-S & DCL-F, the Output specs at the end of the code.

      The DCL-F does not allow for the definition of RPG cycle functionality, including "Input Primary".

      Delete
  15. I had a great deal of trouble figuring out how to define a program defined printer file. Turns out, all you have to do is add the length as a parameter of Printer (ex: dcl-f qsysprt printer(132);)

    ReplyDelete
  16. Hey thanks for the post, i have a question why use keyword PREFIX() in file description is a bad practice for RPGLE? which ways are great to use?

    ReplyDelete
  17. Thanks for this article Simon, i have worked with only /free and now reading all your 'free-form' posts to update myself.

    ReplyDelete
  18. I think that IBM has can define the output specifications like COBOL language. I believe is simple, defining the headers, details and totals lines in data structures and to print, only has to use the write command, using the structures previously defined and indicating the number of lines to skip before or after writing.... What do you think? I think that is not hard to made..... and this way RPG really will be all free to us.

    ReplyDelete
  19. Can someone put a little pgm source-code with these new definitions in it. We are on V7.1 and have the PTF SI51094 installed , but I do seem missing something.

    ReplyDelete
  20. The question I have to ask is what are you "missing"?

    The code given above can be copy-n-pasted into the editor of your choice, therefore, you can take the definitions without a separate source with them all listed.

    ReplyDelete
  21. Is there availability of declaring file in full free-form which is used for pre-run time array?
    If yes, can you please provide an example for the same.

    ReplyDelete
    Replies
    1. Alas, this is not supported in free format RPG (I was trying this a couple of weeks ago)

      Delete

To prevent "comment spam" all comments are moderated.
Learn about this website's comments policy here.

Some people have reported that they cannot post a comment using certain computers and browsers. If this is you feel free to use the Contact Form to send me the comment and I will post it for you, please include the title of the post so I know which one to post the comment to.