The collection of journal and commit APIs includes a number of very useful and powerful APIs. Some of the most prominent candidates for this designation include the Retrieve Journal Entries (QjoRetrieveJournalEntries) API, the Retrieve Journal Information (QjoRetrieveJournalInformation) API and the Retrieve Journal Receiver Information (QjoRtvJrnReceiverInformation) API.
Although the API names certainly are long, the code included with today’s APIs by Example column is aimed at making the time needed for you to take advantage of these APIs correspondingly short.To provide a somewhat realistic context for my presentation of the three APIs, I’ve created the Work with Spooled File Audit (WRKSPLFAUD) command.
On systems having the system audit journal configured to track spooling activity (how-to link provided at the end of this article) the WRKSPLFAUD command also provides a quick and practical tool to investigate events related to printer output as well as document all the stages of a spooled file’s life cycle. More details to follow in a moment.
The QjoRetrieveJournalEntries, QjoRetrieveJournalInformation, and QjoRtvJrnReceiverInformation APIs offer access to journal, journal receiver, and journal entry information similar to that provided by the Display Journal (DSPJRN), Work with Journal Attributes (WRKJRNA), and Display Journal Receiver Atr (DSPJRNRCVA) CL commands, respectively. Put together, that’s an impressive amount of information covering the journaling infrastructure and event and data recording on IBM i.
My example today has its origin in the system audit journal (QAUDJRN) because that seems to be the most common denominator across systems as far as journaling is concerned, but apart from various system uses of the journal facility you can journal database files, data areas and data queues. So using the journal and commit APIs, you could also create monitoring, logging, accounting, and auditing applications and utilities. At the end of this article, I’ve included a couple of links pointing to articles and code examples demonstrating the former two employments of journal entries and APIs.
The QjoRetrieveJournalEntries API provides the foundation for the core function of the WRKSPLFAUD command because it is capable of selecting and retrieving journal entries based on the same comprehensive set of parameters and selection criteria as the DSPJRN and Receive Journal Entry (RCVJRNE) commands. The basic parameter offering includes the range of journal receivers, date and time interval, number of journal entries, qualified job name, user name, as well as program name and journal entry code and type. This array of criteria allows you to narrow your selection of journal entries quite efficiently, and consequently additional parameters can be supported and enforced by the program calling the QjoRetrieveJournalEntries API without incurring a significant performance penalty.