In the preceding installment of the APIs by Example column, I showed an example of how APIs at times offer access to more detailed information than corresponding system CL commands. I also demonstrated how you, as an API programmer, can add more functionality and other enhancements when you create your own API-based versions of system CL commands. The Display Job Open Files (DSPJOBOPNF) command presented last time is today accompanied by yet another example of exploiting system APIs’ access to useful information not easily obtained elsewhere.
Although the Display Job (DSPJOB) and Work with Job (WRKJOB) commands and their related display panels have been enhanced repeatedly over time in order to reflect the conceptual changes and functional enhancements provided for the IBM i OS job entity—such as activation groups, mutexes, and threads—for some reason, IBM has not yet offered much detail as far as job SQL information is concerned—in terms of the mentioned CL commands, that is. The Retrieve Job Information (QUSRJOBI) API, however, has for some time been supporting a return format exposing a job’s SQL-related information. And with release 6.1, this offering has been significantly enhanced with many new job SQL attributes.
The QUSRJOBI API job information return format name for SQL information is JOBI0900, and this format is valid only for active jobs. For jobs waiting on a job queue or jobs that have completed, no SQL information is available. I’m using the JOBI0900 SQL information format as the foundation for the Display Job SQL Information (DSPJOBSQLI) command that I’ve created to accompany today’s APIs by Example article. Since release 6.1’s predecessor, release 5.4, also added vital information to the JOBI0900 return format, the DSPJOBSQLI command was designed to support this release as the earliest.
While developing the DSPJOBSQLI command, however, I ran into some troubles concerning the data actually returned by the QUSRJOBI API for the JOBI0900 return format. For release 5.4 and, for example, prestart jobs waiting to become active, it turned out that some parts of the JOBI0900 format contained “garbage” data. I’ve reported the issue to IBM, and as of this writing, I’m still waiting for IBM’s response. It appears, though, that the issue has disappeared on release 6.1, so for now I’ve coded a workaround to ensure that the DSPJOBSQLI CPP does not fail due to invalid data when run on release 5.4.