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:
D rtnDataStruct 1A OPTIONS(*VARSIZE)
D nFormat 10I 0 Value
D nInLen 10I 0 Value
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:
rtvPtnInfo(myDS1 : 1 : %size(myDS1));
/end-free
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:
D version 10I 0
D reserved1 10I 0
D maxMem 20I 0
D minMem 20I 0
D memInc 20I 0
D DspWheelRotation...
D 20I 0
D LPAR 10I 0
D flags 10I 0
D phyProc 10I 0
D minVirtProc 10I 0
D maxVirtProc 10I 0
D minProcCap 10I 0
D maxProcCap 10I 0
D procCapInc 10I 0
D minIntCap 10I 0
D maxIntCap 10I 0
D ThreadsPerProc...
D 5I 0
D reserved2 6A
D** Note: NAME is in UTF-8 CCSID(1208)
D name 256A
D DefProcCap 10I 0
D DefVirtProc 10I 0
D DefMem 20I 0
D DefCapWgt 10I 0
D DefIntCap 10I 0
The format of the return value for the second format is as follows:
D version 10I 0
D reserved1 10I 0
D OnlineMem 20I 0
D TotalCPUTime 20I 0
D IntCPUTime 20I 0
D AdlCPUTime 20I 0
D UnusedCPUTime 20I 0
D DispatchLatency...
D 20I 0
D flags 10I 0
D phyProc 10I 0
D onlineProc 10I 0
D phyProcCapSharedPool...
D 10I 0
D UnusedProcCap 10I 0
D procCap 10I 0
D VarCapWgt 10I 0
D UnusedVarCapWgt...
D 10I 0
D minReqProcCap 10I 0
D intCap 10I 0
D maxLicCap 10I 0
D groupID 5I 0
D sharedPoolID 5I 0
D intThreshold 5I 0
D reserved3 2A
D UnusedIntCap 10I 0
D reserved4 4A
The following is an example of retrieving partition information using this API, along with the two formats:
D myDS1 DS LikeDS(XT_RTVPTNINF1)
D myDS2 DS LikeDS(XT_RTVPTNINF2)
/free
*inlr = *ON;
rtvptnInfo(myDS1 : 1 : %size(myDS1));
rtvptnInfo(myDS2 : 2 : %size(myDS2));
return;
/end-free
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 of the RPG xTools, a popular add-on subprocedure library for RPG IV. His book The Modern RPG Language has been the most widely used RPG programming book for nearly two decades. He, along with others, speaks at and runs the highly-popular RPG World conference for RPG programmers.
LATEST COMMENTS
MC Press Online