The Retrieve Command Definition (QCDRCMDD) API is useful if you need to retrieve information from a command object about the CL command definition statements required to create the command object. Knowing that the API exists and what it’s capable of, however, is only half the way when it comes to taking advantage of the information returned by the QCDRCMDD API. The QCDRCMDD API returns information in the form of either a return variable or a stream file. If you settle for the return variable, your first challenge is to perform the conversion required to interpret the UTF-8 Unicode character set used by the API to create the output information.
Opting for the stream file will help you overcome this issue, because the IFS stream file APIs required to open and read the output file can perform character set conversion implicitly. You will, however, need to write the code employing these APIs to make this approach work. Irrespective of the output destination chosen, the next challenge is to parse the XML format used to structure and organize the command definition information. Today’s issue of APIs by Example takes a closer look at the aforementioned programming challenges as well as introduces you to four new CL commands that make it easier to get the job done.
As for the XML part of the equation, I’ve naturally taken advantage of the XML parsing functions, the XML-INTO and XML-SAX opcodes, that have been added to RPG IV in recent releases. As luck would have it, a number of useful articles covering this topic in much detail have been published, also in the System iNetwork Programming Tips newsletter. If you need to brush up on RPG IV’s XML parsing capabilities, see the links to these articles at the end of this one.
The first thing I want to do is actually be able to create the XML command definition data. In order to do so, I have to build the Retrieve Command XML Source (RTVCMDXML) CL command, which is basically a front end to the QCDRCMDD API.
The Retrieve Command XML Source (RTVCMDXML) command retrieves information from a CL command (*CMD) object and generates XML source statements that describe the command. The generated command information XML source is called Command Definition Markup Language or CDML. The CDML source is stored in the stream file specified in UTF-8. UTF-8 (CCSID 1208) is a Unicode format that resembles ASCII but allows the data to be stored compactly and shared easily between IBM i systems and any other system that supports the UTF-8 format.