The new (V5R3) Retrieve Partition Information (dlpar_get_info) API returns information about configuration and CPU utilization of the logical partition where this API was called. At least that's what the API documentation says.

But finding information about dlpar_get_info and its cousin dlpar_set_resources can be challenging for touch-typists. If you're lazy and you type only a partial name into the API Finder, you may see results—but for the most part, you won't see a link for this API if you type its full name into the API Finder.

Try it. Go to the API Finder and type in "dlpar_get_info" (without the quotes). Go ahead; I'll wait....

Now try it again, only this time, be a bit lazy and enter only the first five characters of the API name. Try it with just "dlpar" (again, without the quotes).

Voila!

You'll see a list of two APIs that deal with partition information, something like the following:

These two APIs allow you to retrieve and change partition information. The Retrieve Partition Information API is dlpar_set_resources, which is an interesting name in and of itself. It returns the current configuration of the partition from which the API was called. The information is similar to that returned by the MATMATR MI instruction. The information is in a more useable form and is easier to retrieve using this API than using MI, of course. The gotcha is that you have to be on V5R3 or later to use it; otherwise, you need to perform MI programming or license the RPG xTools from Linoma Software to get this kind of information.

Fortunately, surveys indicate that most iSeries shops have moved to V5R2 or later, which I hope means V5R3 (or later). Personally, I have little use for V5R2 and would recommend jumping directly to V5R3 if you can.

To use this API, you need an RPG IV prototype. The following source code provides this prototype:

I've named this prototype RTVPTNINFO to more closely resemble what it does and to make it easier for me to remember.

The first parameter, which is the return data parameter named RTNDATASTRUCT, is declared as a 1-byte field that includes OPTIONS(*VARSIZE). This allows us to specify a field (or more accurately, a data structure) of a different length than that of the declaration.

The actual length is controlled by the third parameter. So, for example, if you wanted to call this procedure and pass to it a data structure named MYDS1, it might look something like this:

In virtually every other API that came before this one, the length of the return parameter immediately followed the return parameter. That is, the length would traditionally have fallen as the second parameter, not the third. But who said the iSeries was trying to be consistent?

OK, regardless of the unexpected parameter sequence, the API returns the information about the current partition. Before you ask, no, you can't get information about other partitions by using these APIs.

The partition information is returned to the first parameter in two formats. The format of the data returned is controlled by the second parameter. Once again, previously the format ID of APIs was traditionally an 8-byte character value that was effectively used like a record format name; OBJD0100 is one example. This API uses integers instead: Pass a value of 1, and the first format is returned; pass a 2, and the second format is returned. I actually prefer this style of format ID—so much in fact that I chose it for my RPG xTools service program.

The two formats return different types of information. The first format returns information that is effectively static as it relates to the partition—that is, information that is unlikely to change without reconfiguring the partition, such as the partition size.

The second format returns information that is likely to change at any time, such as the total CPU time used and CPU time unused. But a number of static properties are also returned in the second format.

The format of the return value for the first format is as follows:

The format of the return value for the second format is as follows:

The following is an example of retrieving partition information using this API, along with the two formats:

Compile the above example with DBGVIEW(*SOURCE) and then step into the code. Set a break point at the RETURN statement and then call the program. When the breakpoint is met, display the content of MYDS1 and MYDS2. Since they are both qualified data structures, their subfields will be displayed with the data that is contained in them.

Managing Partitions

More and more iSeries are being shipped and installed with at least two partitions. At some point in the near future, I expect most to be multiple-partition boxes. The tools to determine partition configuration and modify it are slowly becoming exposed to the application developer. It's important to play with this stuff early so that it doesn't become just another feature.

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.

---

MC Press books written by Robert Cozzi available now on the MC Press Bookstore.

		RPG TnT Get this jam-packed resource of quick, easy-to-implement RPG tips! List Price $65.00 Now On Sale
		The Modern RPG IV Language Cozzi on everything RPG! What more could you want? List Price $99.95 Now On Sale

Also Read

The Importance of BIFs, BIF Essentials

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs