In the previous installment of the APIs by Example column (see “APIs by Example: Command Definition API and API XML Output Processing,” December 9, 2010, article ID 65648), I demonstrated the Retrieve Command Definition (QCDRCMDD) API and how its output can be parsed with RPG’s XML-SAX opcode. Today, I continue with that theme, this time from the perspective of how you can use existing IBM CL commands to speed up and ease the task of creating your own CL commands.
To help me do so, I’ve created a CL command front end to the Rename Object (QLIRNMO) API, in turn simplifying the task of moving and replacing an object, moving and renaming, or both, all in one single operation. I’ve also included a brief CL program giving an example of how to take advantage of the Move and Rename Object (MOVRNMOBJ) CL command in the context of retaining a number of previous versions of a transaction work file created and processed, on, for example, a daily basis.
The QLIRNMO API is more than just a combination of the functions provided by the Move Object (MOVOBJ) and the Rename Object (RNMOBJ) commands. It also provides an option to replace the target object when it already exists, a situation in which both of the aforementioned commands would fail. This means that your code does not have to handle this situation separately but instead can set the QLIRNMO API’s Replace object parameter in accordance with the behavior you’d want for that particular situation.
In this example, I’m specifying the QLIRNMO API directly as the MOVRNMOBJ command’s CPP. All QLIRNMO API parameters can be mapped directly to the parameter types offered by a command definition. In this case, I decided not to create a separate CPP to call the QLIRNMO API. If I had chosen to include a command completion message or wanted to offer special values for the MOVRNMOBJ command parameters, I would need a CPP to convert them into valid API parameters. If I did that, I’d have to spend some time wrapping up the API call, but in this case, I saved myself the extra work.
The only challenge with such an approach is the standard API error data structure that most APIs require. A command definition, however, can specify a command parameter as a constant. This means that you specify the value of the parameter directly in the command definition statement for that parameter. The command will not display constant parameters on a command prompt but instead will simply pass the specified parameter value to the CPP. This allows me to exploit the standard API error-handling convention, dictating that passing a four-byte integer with the value zero as the error parameter to the API will cause the API to communicate error conditions by returning an exception message straight to the API caller, in this case being the caller of the command.
Articles on Apis 
One thought on “APIs by Example: Move and Rename Object API, and IBM CL Command Reuse”