Looking back at when I first started writing articles for PowerWire.eu nine years ago, I was bought onboard to cover RPG articles. Looking back over the last few years I have failed miserably in this task and maybe got too carried away in the ‘open-source’ frenzy.
In this anniversary month for the IBM i we must not forget the strenghts of the marriage of RPG and the IBM i. I’m sure that one will not last without the other.
So onto this article, and yes it is about RPG!
The DATA-GEN op code is used to generate a structured document, is very powerful and worth an article on its own.
The DATA-GEN op code can be considered very similar to the DATA-INTO op code, but where the DATA-INTO is used to read a source, the DATA-GEN op code is used to write data, or convert it.
This operational code has 3 parameters to it and has the syntax as shown in the figure below.
1. The first is the variable used as input, the variable we want to convert. This is usually a data structure but doesn’t have to be, it could be a defined standalone variable.
2. The second parameter is the path to save the document, or result variable, to on the IFS. Normally a path location to save the generated document to.
3. The third parameter is the name of the program, or service program, to convert our variable. This is yours, or a supplier’s, program, that does exactly what you want it to do for the conversion.
Let me show you an example of how this could be coded in an RPG program.
In this example, we are going to take a rpg data-structure containing our employee details, and create a json object from that data structure.
The json object will be stored in my home directory on our IFS, often abbreviated to the ~ symbol.
Let me step through the code in this example.
Firstly, we have a qualified data-structure that holds employee details.
It has six sub-fields to this structure, all initialised.
This data-structure will be converted to a JSON format by our DATA-GEN op-code.
Next, I define a standalone variable to store the location of our conversion, which can be seen in the figure below.
Now we have those couple of lines defining our variables, onto the op-code.
As I described in the syntax explaination, the first parameter is the variable, or data-structure to convert.
Then in the %DATA parameter we specify the location of the converted variable. In this parameter we also specify a couple of additional parameters, the DOC to specify it’s a file to convert, the file CCSID to use, and to clear any previous output. These are just a few of the available parameters to the %DATA part of this op-code. Check IBMs documentation for full details.
Onto the %GEN parameter. This specifies the name of the conversion program that will be used to convert our data-structure to JSON format, and can also have additional parameters similar to the %DATA part. These will be specified in the documentation of the conversion program.
The YAJLDTAGEN program was kindly provided by Scott Klement and can be downloaded from his website – Thanks Scott!
Just to be sure our conversion gave the correct results, I pasted the resulting JSON file into an online JSON checker at https://jsonformatter.curiousconcept.com/ which confirmed that everything translated correctly.
Please note that the DATA-GEN op-code can also be specified with the E (Error) handler, if you need to trap any errors generated by the op-code.
In this conclusion I must thank my fellow IBM Champion Scott Klement for his excellent explanation of this op-code and his conversion program.
If you wish to write your own conversion program, IBM has provided some examples of conversion programs in the QOAR library for you to use and modify at your will.
The enhancements like DATA-GEN, that IBM has introduced over the last few years shows that they are still continuing to ensure that the RPG language does not fade away and keeps up with all its open-source counterparts.
All the examples I have written for this article, and previous ones, can be found on my companies open-source repository on GitHub, which can be found at https://github.com/formaserve/f_Learning
If you have any questions, either on this article, or anything else on the IBM i, please use the comments below, or send me a message on twitter @AndyYouens
Andy Youens is an IBM i consultant/instructor at Milton Keynes, UK-based FormaServe Systems with over 40 years IBM midrange experience.