The New CHAIN Operation: This Is Not Your Father's CHAIN Op Code

by Kevin Vandever

The CHAIN operation is an RPG programmer's friend. It has been around for decades, and we are so thankful for and comfortable with its existence that when we hear the word "chain" spoken outside of IT we automatically think of random record retrieval from a database file. Well, get ready because the CHAIN operation is a changin' and although it will continue to be our friend, it has been kicked up a few notches by IBM and is ready for the next generation of RPG programmers.

Old School CHAIN

Let's first discuss the CHAIN operation as most of us know it. This is the basic structure:

C	Key         CHAIN       File                    9997
C   	                If                *In97
C	                Do some error handling
C		    EndIf
    
C		    If                Not *In99
C	                Do something with data
C		    Else
C	                Do something if record not found
C		    EndIf

Of course, there are variations on that theme, but the point is that CHAIN is used to access a file, given a key or search argument, and if the record is not found, an indicator (99, in my example) is set on. I added another indicator next to the found/not found indicator to allow me to check for errors. The error indicator (97) will be set on if a status code greater than 1000 is returned during the CHAIN operation. We've used this kind of code for years. Then a few OS/400 releases ago, IBM removed the need for indicators (amen, brothers and sisters) and gave the CHAIN operation--as well as the other file access op codes--a much needed improvement. Now our beloved CHAIN example looks something like this:

C	Key         CHAIN       File                                        
C	                If                %Error
C	                Do some error handling
C		    EndIf

C	                If                %Found
C	                Do something with data
C		    Else
C	                Do something if record not found
C		    EndIf

You don't have to remember if the indicator is set on or off when the record is found or an error occurs, because there are no indicators. And debugging code is much easier because you can quickly tell which is the found logic, which is the not-found logic, and which is the error logic, thanks to the new built-in functions. Subsequent enhancements to RPG, in V5R1, completely changed the way you handle errors on file access. For an explanation of those enhancements, check out the article "CL-Like Error Handling in RPG."

CHAIN in V5R1

The RPG enhancements in V5R1 blew us all away. IBM added a new way to code, comment, and end a line, with free-formed calculations. Also added to the language were new op codes, new functions, new data-types, and much more. Along with all of this, the CHAIN operation was slightly modified. This modification allows you to use the CHAIN operation in free-formed calculations. The format is as follows:

       	CHAIN  Key   File;
	If  %Found;
	    ExSR Somthing;
	EndIf;

The CHAIN structure is a little different in free-formed syntax. The op code goes first, followed by the search argument and the file. A semicolon (;) is used to end a line. For more information on free-formed calculations, go to "Let Your Hair Down With Free-Formed C-Specs."

CHAIN in V5R2

What CHAIN missed out on in V5R1 it more than made up for with the release of V5R2. For starters, if you are accessing an externally described file, in addition to a KLIST, as your search argument, you can now list a series of values. This is only allowed in free-formed syntax and would be coded as follows:

	CHAIN ('12345' : '01')  File;
       If  %Found;
        ExSR Something;
    EndIf;

This tells the CHAIN operation to use the composite key made up of 12345 and 01 to access the file. You can also use field names as values:

       CHAIN (FieldA : FieldB)  File;
       If  %Found;
        ExSR Something;
    EndIf;

Where this enhancement really takes off is in its ability to handle expressions. Check this out:

   CHAIN (%SubSt(CusNum : 1 : 5) : CompanyNum + StoreNum) File;
   If  %Found;
    ExSR Something;
EndIf;

The composite key in the previous example is made up of the first five characters of the CusNum field, along with the combination, or concatenation, of the CompanyNum field and the StoreNum field. Your expressions can be as complex and long as you need them to be. In this case, I am resolving two key fields. If your file has more, you will have more values or expressions, separated by colons (:).

Another enhancement to the CHAIN operation in V5R2 is the ability to place the data from a successful CHAIN into a data structure. You have had this ability for program, or internally described, files for some time, but as of V5R2 you can do this with externally described files. Here is how you code it:

D FileDs       ds                  likerec(FileRec)
                                        
      // Read the record directly into the data structure
      CHAIN (FieldA : FieldB)  File FileDs;

     // Use the data structure fields
      If  %Found
           DsplyFname = FileDs.Fname;
           DsplyLname = FileDs.Lname;
      EndIf;

This enhancement is a little more involved. At the end of the CHAIN operation, you can see the data structure name, FileDs, which was defined in the D-specs. This allows you to take the contents retrieved with a successful CHAIN and place them in that data structure. This enhancement works for both free-formed (as shown above) and traditional C-specs. Notice the D-spec in the above code. I added this to show you that in order to use this enhancement, you have to define the data structure properly. You can do this with the new (V5R2) LIKEREC keyword or the modified EXTNAME keyword. The LIKEREC keyword allows you to define a data structure, data structure subfield, prototyped return value, or prototyped parameter like a record, based on an external record format (in this case, the record format for File). The LIKEREC keyword has two parameters. The first parameter is the record format name, and it must be a record format from a file defined in your file specification (more than likely, the file you will CHAIN to). The second parameter tells which fields you want to include in the data structure. The options are as follows:

• *ALL--All fields in the external record are extracted.
• *INPUT--All input-capable fields are extracted. (This is the default.)
• *OUTPUT--All output-capable fields are extracted.
• *KEY--The key fields are extracted in the order that the keys are defined on the K specification in the DDS.

However, to define the data structure to be used in a CHAIN operation, you can only use the *INPUT option in the LIKEREC keyword. Data structures defined with LIKEREC are qualified data structures, so you can use them as I did in my example with the data structure.field name format. An enhancement was also made to EXTNAME keyword to also include which records you want to include in the data structure, so you can use that keyword, too. The same restriction holds true, that you have to use the default value of *INPUT.

So when would you use something other than *INPUT? That brings me to the last enhancement to the CHAIN operation. In addition to a KLIST entry and a list of values, you can use the new %KDS built-in function to reference search arguments in a data structure. The following block of code shows how this technique would be used:

FOrderFile  if   e           k disk    rename(ORDR:OrdRec) 
D OrdRecKeys     ds                  likerec(OrdRec : *key)

/free
   // OrdRecKeys is a qualified data structure
   OrdRecKeys.OrderNum = wOrderNum;
   OrdRecKeys.OrderLine = wOrderLine;
   // the *KEY data structure is used as the search argument for CHAIN
   chain %kds(OrdRecKeys) OrderRec;
 
/end-free

As you can see, the file name is OrderFile and its record format is OrdRec. I used the RENAME keyword so you could see the record format name. Then I define a data structure based on the OrdRec record format, except that this time I used the *key parameter, which dictates that only the key fields are to be defined in the data structure. In my example, assume OrdFile contains two keys, OrderNum and OrderLine. The OrdRecKeys data structure will contain subfields to match the keys, and only the keys, in the same order that they exist in the physical file. This is a qualified data structure, so you can populate the data structure appropriately and use that data structure with the %KDS built-in function to CHAIN to the file or record format. Pretty cool, right?

Our Little CHAIN Has Grown Up

The CHAIN operation has undergone quite an evolution. The good news is that you can still use CHAIN as you always have and employ only the new enhancements if you want to. The CHAIN operation has become more flexible and powerful, while still maintaining its charm. These enhancements, along with most of the enhancements to the language, help to keep RPG alive and prepare it for future generations of RPG programmers--if there are any.

Sponsored By PROFOUND LOGIC SOFTWARE

Don't be left behind! Thousands of programmers have adopted RPG-Alive, and are now able to read and understand RPG code 2 to 3 times faster. To try RPG-Alive on your system, visit http://www.RPGAlive.com/now "I am very happy with RPG-Alive! It's a terrific productivity booster!" says Brian Johnson of Help/Systems. See other user testimonials at http://www.rpgalive.com/testimonials.html