Externally Described Database IO through Data Structures

Published: October 24, 2007

by Ted Holt

Eons ago, IBM enhanced the RPG compiler by allowing program-described files to define data formats using data structures instead of Input and Output specs. I have taken advantage of this ability from time to time since then, and would be willing to testify in anybody's court of law that I don't miss I and O specs one little bit. It was much later, in V5R2, that IBM decided that data structures should be allowed for externally described files as well. I was not so excited about this decision until recently, when I realized that the use of data structures for externally described database files could help me improve the "clonability" of a certain file-maintenance template that I clone on a frequent and recurring basis. But first I had to learn to use externally described data structures correctly.

Let's say that I have a database file that I want to access in several ways. I want to read it forward, read it backward, read it randomly, update it, delete records from it, and add new records to it. (This is no joke. The template really does include all those operations.) Input operations, such as READ and CHAIN, have to use a data structure that is defined to include the input fields of a record format.

D CusDataIn       ds                  likerec(CusRec:*input)

 /free
     chain %kds(CusKey) CusRec CusDataIn;

The sole output operation, WRITE, has to use a data structure that is defined to include the output records of a record format.

D CusDataOut      ds                  likerec(CusRec:*output)

 /free
     write CusRec CusDataOut;

The UPDATE op code accepts either one of those definitions.

What this means is that you can't use the same data structure for both input and output operations, even if the input and output layouts are identical. You can read into data structure XYZ and you can update from XYZ, but you can't write from XYZ. I consider this a nuisance, because I don't want to define two data structures for each record format and have to shuttle data back and forth between them.

The solution I settled on was to define each input-output data structure pair to occupy the same memory, so that modifying one data structure automatically modifies the other. My first attempt at this worked fine, but it was ugly, involving the use of pointers (Yuck! Blech!) I emailed my code to the patron saint of RPG programmers, Barbara Morris, of the RPG compiler development team at IBM Toronto. She had a better idea. (Of course.) Barbara moved the two data structures into subfields of a qualified data structure and used OVERLAY to place the output format on top of the input format.

D CusData         ds                  qualified 
D   In                                likerec(CusRec:*input)
D   Out                               likerec(CusRec:*output)
D                                     overlay(In)

 /free
     read  CusRec CusData.In;
     // do some stuff
     CusData.In.City = 'Lost Angeles';
     CusData.In.State = 'ID';
     write CusRec CusData.Out;

Thanks to Barbara Morris and externally described I/O through data structures, my new program runs as smooth as a sewing machine.

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot