<i>Can someone tell me how to use this?</i>
Use it like RGZPFM has always been used. (More later…)
<i>Does this come with the operating system or is it a separate module we would need to purchase?</i>
It’s been in i5/OS since V5R3. It’s standard.
<i>I would appreciate seeing an example of how this works in a CL.</i>
RGZPFM FILE( MyFile ) ALWCANCEL(*YES)
I suspect that that’s not what you were thinking, but that’s definitely a working example. A real production version would probably include a MONMSG for CPF2981, and possibly error processing would receive *DIAG messages such as CPF3202 — “File MyFile in library MyLib in use.” How you handle those is up to you.
Really, all you need to do to study it is create and populate any PF. Use DSPOBJD to an outfile, then run RGZPFM over it. Once you get that part working, have a session bring your test file up in a RUNQRY list, and try RGZPFM again.
First thing you’ll find is that the file must be journaled before ALWCANCEL(*YES) is allowed. The reorg is done by way of a kind of “commitment control” (for lack of a better term; it’s probably not correct). The file appears to be reorg’d in large segments through the journal. One result is that some additional space must be available to hold the receiver as it grows during processing, but I don’t know if the relative size is significant. (We reorg’d a 330GB table on a system that didn’t otherwise have sufficient space for a straight reorg.)
Second thing you’ll learn is that there is a point where an *EXCL lock is needed. IIRC, that happens near the end of the reorg process, and it should only last for a small fraction of the total time. It might only be a few seconds. I haven’t found a precise way to test its limits. The RUNQRY I suggested earlier would help illustrate how the timeout on the lock can work. If you have the file listed, the RGZPFM will block when it reaches its lock point. Unless you let go of the file in time, the timeout will throw the CPF2981 message along with a diagnostic. If your target files are open 24/7, then you’re still out of luck. But if they open and close regularly, then default wait times might be sufficient.
Beyond that, if the command is canceled, it should mostly start where it left off when you execute the same command later.
One potentially troubling element involves variable-length fields (including the various LOB fields). If RGZPFM is canceled, the overflow (auxiliary area beyond the ALLOCATE() limit) is not reorg’d. The RGZPFM must actually run all the way through to recover fragmented space in the overflow area. The fixed area seems to compress fine.
Other than that, I’d simply suggest creating a PF and running tests. It’s easy enough to do.