Print Directly to a PDF File on the IFS
NOTE: RPG Report Free Preview Has Ended
Our
two February issues require no membership, our two March issues
require a free membership, and all subsequent issues of RPG Report
require a Premium (paid) membership. Learn more about our
membership choices here.
Around V4R2 a small group of former IBM Rochester Engineers retired and started a small software company. That company's purpose was to
bring non-traditional interfaces to the IBM i platform. They successfully
created or ported everything from a graphical user interface, 5250
emulation, zip file compression and time synchronization. One of their biggest sellers was a
driver that allows you to move a SPOOL file to a specific output
queue; and output queue that magically transformed the SPOOL file into a PDF file. It works like magic and is still available from the
company's website.
Native PDF Print Support
Jumping ahead to today; when IBM i OS v6r1 was shipped, IBM provided its own
built-in PDF driver. Unlike the output queue approach described above (which
continues to be viable today and there is still no IBM PDF alternative) this
new IBM PDF driver works in conjunction with Print
File attributes. Just like the PC, to create a PDF file from a document, you
override the printer driver and write to the output device. This is done on
IBM i by issuing an OVRPRTF command or by creating a print file that
includes the PDF
attributes. To
me, the OVRPRTF command is the obvious choice for this
functionality.
PDF Prerequisites
To utilize the IBM i PDF driver, you need to make sure you've installed the TS1 licensed program.
If you're running v6r1 the product ID is 5661-TS1, if you're running v7r1 or
later the product ID is 5770-TS1. You will need to install both the *BASE support and option 1. Here's
the summary:
v6R1m0 - 5661-TS1
v7R1m0 - 5770-TS1
*BASE IBM Transform Services for i5/OS
1 Transforms - AFP to PDF Transform
If you have these prereqs installed, you are ready to start generating
PDFs on your system today. In addition to the above software packages, authority to issue
the OVRPRTF command and access an IFS folder is required.
Similar to directing output to
Adobe Acrobat or
the freeware CutePDF PDF driver on PC platforms, when a PDF image is
created on IBM i, it must be directed to a file on the IFS. IBM i PDF
support does not prompt you for a file name at runtime (at least I haven't
had that experience) but instead requires that the file name be specified
before the print file is open. It is remarkable how well this logic
integrates with IBM i applications. If you're producing an A/R
ledger report for example, the name LEDGER.PDF would be a good file name.
Perhaps storing it in a folder named /home/apps/ar might be desirable. So
the name you would identify to the OVRPRTF command would be: '/home/apps/ar/ledger.pdf'.
Magic PDF Command
The CL command and interfaces on v6r1 and later needed to create a PDF are so simple, it makes you
wonder why IBM didn't implement it sooner. (That's a left-handed complement,
by the way.) To create a PDF instead of a SPOOL file, add the following 3
parameters to an OVRPRTF command:
Parameter Definitions:
DEVTYPE - This is the device type. This parameter must always be
set to DEVTYPE(*AFPDS) to create a PDF file.
WSCST - This is the Workstation customizing object. This parameter
must always be set to WSCST(*PDF) to create a PDF file.
TOSTMF - The path and optional PDF file name to be created. You
must specify an IFS path, but the file name may be auto-generated.
The DEVTYPE and WSCST are always the same, but the TOSTMF parameter is
the one that varies based on the situation. Specify either a fully
qualified PDF file name (IFS path and the PDF file name) or specify only an
IFS path/ When an IFS path is specified and a PDF file name is not included,
the system will generate a file name for you. Here are two examples that
illustrate these options.
OVRPRTF FILE(QPRINT) DEVTYPE(*AFPDS) TOSTMF('/home/cozzi/ledger.pdf') WSCST(*PDF)
In this example the file ledger.pdf in the /home/cozzi directory
will be created from the output written to the QPRINT file.
OVRPRTF FILE(QPRINT) DEVTYPE(*AFPDS) TOSTMF('/home/cozzi') WSCST(*PDF)
In this example, the specific PDF name on the IFS is not specified. In
this situation, the system generates a name using the Print file name and a
random 6-letter pattern.
/home/cozzi/QPRINTxxyyzz.pdf
Where xxyyzz is a random character pattern that insures unique file
naming.
To print source member from within PDM to a PDF file, I issued the following OVRPRTF command
to the QPSUPRTF print file and then used PDM option 6
(print) on 3 of my source members.
OVRPRTF FILE(QPSUPRTF) DEVTYPE(*AFPDS) TOSTMF('/home/cozzi') WSCST(*PDF) OVRSCOPE(*JOB)
This produced the following 3 PDF files in the /home/cozzi
directory on my IFS:
QPSUPRTFcb16DX.pdf
QPSUPRTFLDzcXw.pdf
QPSUPRTF2h8Vtc.pdf
To make the auto-generating names more clear, I have replicated them
below, this time, separating the prefix used in the print file name from the unique identifier
generated by the PDF driver:
QPSUPRTF cb16DX.pdf
QPSUPRTF LDzcXw.pdf
QPSUPRTF 2h8Vtc.pdf
From this you can see that when the PDF driver is asked to generate a PDF
file name, it uses the print file name as a prefix, followed by 6
random characters, and then finally the '.PDF' file extension.
OVRPRTF, CHGPRTF and CRTPRTF
In addition to using OVRPRTF to direct output to a PDF file, you can
permanently assign PDF output to an existing print file. Simply issue a
CHGPRTF (Change Print File) command and specify the same values as used on
the OVRPRTF command. If you are creating a new print file, you can easily
specify PDF output by specifying the DEVTYPE, WSCST and TOSTMF parameters on
the CRTPRTF (Create Print File) command.
Remember, if you are running IBM i v6r1, make sure you have 5661-TS1
installed. If you're running v7r1 or later, make sure you have 5770-TS1 and
it should just work. You will need *BASE and Option 1 of the licensed
program.
That's all there is to it.
Ad
Conclusion
For years IBM has been adding questionable interfaces to the system; mostly due to the fact that the System/38
Generation of Engineers retired or moved on to other things, but some
are still there. This implementation of PDF
support is very promising and surprised me; but in a good way. If you
look at the great work IBM did here and in rewriting the CPYTOIMPF command
back on V5R1 or V5R2 (replacing the previous, unusable implementation) it looks like IBM Rochester is really putting worthwhile efforts into
this platform, and that's a good thing.
Call Me
If you have any questions on any area of RPG IV,
Web development, API, C/C++ or anything else IBM i development related (except subfiles,
data areas and RPGII/III because I don't care about that stuff) write a comment to me on our
website and I may include a response in an upcoming issue of RPG
Report.
You can subscribe to RPG Report (we call it "follow") by
visiting RPG Report
on midrangeNews.com and click the FOLLOW link in the table of contents on that
page. To unsubscribe, simply click that same link. You must be
signed up for, and signed
in to midrangeNews.com to start following RPG Report.
-Bob Cozzi
Follow Bob on Twitter