As the APIs become more powerful, they need more complex parameters to control their behavior, and this article shows how to build those complex parameters.

Previous articles in this series have provided direction on how to call an API and how to return errors, but the API interface has been pretty simple. In this installment we're going to look at an API with one of the more complex parameters and learn how we can use all the power of ILE RPG to help us define that parameter.

Retrieve Journal Entries (QjoRetrieveJournalEntries)

If you use journals, you're familiar the DSPJRN command, which takes a wide variety of parameters. These include the receiver range, starting timestamp, ending timestamp, journal codes, journal entry types, and so on. And while this command provides a great deal of flexibility, it isn't always ideal for what we need when trying to analyze journal activity. As a very simple case, if you want to check for activity from a list of programs, you have to run DSPJRN once for each program name. This isn't very efficient.

The better solution is to use the Retrieve Journal Entries API (QjoRetrieveJournalEntries) to spin through all the journal entries (or at least a more inclusive subset) under program control and do the filtering yourself. And that's where we run into the idea of the "variable record" parameter.

Let's start by going to the IBM web page for the QjoRetrieveJournalEntries API. This page has a lot of information, starting with the parameter list.

Figure 1: This is the parameter list for the QjoRetrieveJournalEntries API.

You'll see that there is a required parameter group and an optional group; this is very common among IBM APIs. We'll be diving more into these parameters in a subsequent article, but for today we're just going to focus on one parameter in particular, the "Journal entries to receive" parameter. This parameter is used to identify the selection criteria for entries to be retrieved from the journal. It uses the variable-length record concept to specify multiple filters.

Variable-Length Record Parameters

The concept of a variable-length record parameter is simple: The parameter is a data structure where the first four bytes identify the number of records in the rest of the data structure. Each record has a specific structure, which starts with the length of that record.

Figure 2: Each variable-length record has this layout.

The structure is quite rigid right up until the last value, the actual data. Each of the first three values is a 4-byte integer (specified as int(10) in RPG). The first is the length of the entire record, the second is a key identifying what kind of data is in the record, and the third is the length of the data. It's hard to really express how these values work in words, so let's take a look at an example.

Figure 3: A variable-length record parameter with two records looks like this.

The header is just an integer with a value of 2. This tells the API there are two variable-length records to follow. The first one is a type 1 record, which is used to specify the receiver range. That data consists of four 10-character components (what they are isn't important yet), so the third integer, Data Len, is set to 40. The second integer is set to 1 since, as we noted, this is a type 1 record. That leaves the first value, which is 52. That makes sense because the entire record consists of 40 characters of data and three 4-byte integers, for a total of 52 bytes.

The next record is very similar, except the data is only 26 characters (long enough to hold the character value of the starting timestamp), and thus the first and third values are 38 and 26, respectively. The second integer is set to 3 to indicate this is a type 3 record, a FROMTIME record. (All these types are defined on the same web page.)

These records each butt up against one another to make a complete parameter. The length of the entire parameter in this case is 94 bytes total. So now it's time to see how these are defined in an RPG program.

Using Data Structures to Defined Variable Length Records

What I like about using ILE RPG to call this API is how I can take advantage of data structures to build the selection parameter component by component. The following code shows the free-format RPG code used to define the header and the two data structures depicted in Figure 3.

// Retrieve journal entry selection records    

dcl-ds JrnEntRtv qualified;                                  

  NbrVarRcd int(10);                                        

end-ds;                                                      

// RCVRNG - *CURCHAIN - Reset this to get first entry in chain

dcl-ds JrnVarR01 qualified;                                  

RcdLen int(10) inz( %size(JrnVarR01));                    

Key int(10) inz(1);                                        

DtaLen int(10) inz( %size(JrnVarR01.Dta));                

Dta char(40) inz( '*CURCHAIN' );                          

   RcvStr char(10) overlay(Dta);                            

   LibStr char(10) overlay(Dta: *next);                    

   RcvEnd char(10) overlay(Dta: *next);                    

   LibEnd char(10) overlay(Dta: *next);                    

end-ds;                                                      

JrnEntRtv is the header, while JrnVarR01 and JrnVarR03 are the definitions for the type 1 and type 3 variable-length records, respectively. All of them use qualified data structures. While not perhaps strictly necessary for the header, using qualified data structures is critical for the variable-length records because they all use the same names for the first four fields (RcdLen, Key, DtaLen, and Dta). Remember, these all use the same basic structure as shown in Figure 2. Note how we use a self-referential INZ keyword on the length fields to initialize their values.

If you compare the two data structures JrnVarR01 and JrnVarR03, you'll see that the Dta field in JrnVarR03 is very simple; it's just a 26-character field that will be initialized later. But for the JrnVarR01 field, you'll see that the Dta field has subfields defined using the OVERLAY keyword as well as the entire field being initialized to the value *CURCHAIN. That's because you can specify a receiver range by specifying the name and library of both the start and end of the range, or you can use the special value *CURCHAIN with the rest of the field blank to select the entire range. We define the data structure to allow both syntax variations because we'll need them when we're processing the journal in a loop.

Calling the API

To call the API, we need (as always) two things: the prototype and the code that calls the prototype.

dcl-pr RtvJrnE extproc( 'QjoRetrieveJournalEntries');  

RjRcvVar     char(32767) options(*varsize);          

RjRcvVarLen int(10)     const;                      

RjRcvJrnNamQ char(20)   const;                      

RjRcvInfFmt char(8)     const;                      

RjSltInf     char(32767) options(*omit:*varsize) const;

RjError     char(32767) options(*omit:*varsize);    

end-pr;                                                

The prototype is simple; it matches the definition of the API found in Figure 1. We can have some discussion on *VARSIZE and *OMIT at a later date, but this prototype will work as needed. The one thing that's probably most interesting is the fact that we use CONST on the RjSltInf parameter. This is the place where our variable-length records go, and it's important to define it as a CONST for reasons that will become immediately apparent.

// Number of selection criteria = 2                      

// 1. Receiver range (type 1)                              

// 2. Starting timestamp (type 3)                          

JrnEntRtv.NbrVarRcd = 2;  

// RESET sets the DS back to *CURCHAIN                      

reset JrnVarR01;                                            

// Set the timestamp back three days from today

JrnVarR03.Dta = %char(%timestamp() - %days(3));          

// Use ApiError1, returns the message ID                    

reset ApiError1;                                            

RtvJrnE( JeRcvVar : %Size( JeRcvVar ) : iJrnLib : 'RJNE0200':

         JrnEntRtv + JrnVarR01 + JrnVarR03: ApiError1);  

This is the actual call. I'll be happy to spend plenty of time on this and other code in the utility in another article, but for today I really just want to talk about how the records are initialized and then sent to the API. First, the initialization. We set the NbrVarRcd parameter to 2 to indicate that there are two variable-length records. We reset JrnVarR01 so that it's initialized to *CURCHAIN, and we compute the Dta field in JrnVarR03 to be three days prior to right now. We reset the error API (you can review how that works in the first article in the series) and call the API.

The call to the API is the really cool thing. Because the API uses the length of each record to find the start of the next, I just string them together: JrnEntRtv + JrnVarR01 + JrnVarR03. If I had more records, I could just add them to that expression (making sure, of course, to set the NbrVarRcd field accordingly).

Imagine how hard this would be to create as a single data structure, especially if you needed to include different records on different calls to the API. This technique of concatenating multiple individual data structures into a single parameter has made this API eminently accessible to me, and with any luck I can pass that to you.

In closing, I would like to once again point out that my work here is built upon the pioneering efforts of Carsten Flensberg, available on his website, API - My My.