IBM initially conceived APIs to provide programmers with a well-documented and well-structured interface to system information that in the pre-API days was obtained by parsing CL command spooled file output or by calling IBM system internal programs directly. In addition to APIs’ versatility and standardised interfaces, they also often offer much more information and details than their original CL command counterpart.
Today’s APIs by Example demonstrates an API that in itself exposes more information about a job’s open files than is available elsewhere. At the same time, true to the concept of a programming interface, the API approach lets you further enhance the functionality associated with the resulting Display Job Open Files (DSPJOBOPNF) CL command, compared to the corresponding native offering. The List Open Files (QDMLOPNF) API delivers the core command functionality of listing a specified job’s currently open file objects.
The IBM CL commands Display Job (DSPJOB) and Work with Job (WRKJOB) both support an OPTION(*OPNF), which, in the words of the associated help text, performs a similar service: “Files that are open for the job and the status of system and user files are shown.” Programmers often refer to these commands and this option to examine and verify the files that their programs have opened, and the type of operation being performed against these files.
You can see the relative record numbers of the file records as they’re being processed, and you can verify the libraries of the files opened. For anyone who has ever enjoyed the outcome of testing an update program against a production file, the latter is a very useful capability. There’s a column specifying the number of I/O operations performed to the respective open files, and information about activation scope and activation groups. For many programming tasks, the DSPJOB or WRKJOB command’s Display Open Files panel will help you get your job done. But in some situations, this panel has shortcomings.
There’s no specification of the individual types of output being performed: write, read, write/read, and other I/O. You only see the accumulated result in a single column. The limited column size for the I/O count as well as the relative record number at some point causes overflow for jobs performing either excessive I/O for longer periods of time or processing large files. Using the function key F5 to refresh the screen after paging down one or more pages immediately takes you back to page 1. You have no way of limiting the list panel to include only particular files, libraries, types of files, or I/O.
As upcoming issues of this column will further demonstrate, you have the happy option as an API programmer, and given the presence of an appropriate API, to build the tools you need in order to make your job a little easier and the outcome of your efforts a little better.
Download the save file containing the source code.