Alignment and appearance of your PDFs
Some of the most common questions asked about CVTSPLPDF are:
- I am having an issue with alignment of the overlay and the content.
- The right hand side of the document is cut off.
- The user would like to make the font a little bigger.
This article is an attempt to explain how to improve the appearance of PDFs created with CVTSPLPDF. It will not answer the questions specifically but highlight the parameters that affect the appearance of the resulting PDF. It is not definitive and will be updated periodically.
My overlay doesn't line up properly
Overlay alignment is a complex area, and how an overlay lines up on the page can sometimes be dependent on factors that CoolSpools can't know about without additional information, such as what kind of printer you're using and how its margins are set etc.
By default, CoolSpools emulates a true IPDS printer, but if you've developed your application for a Host Print Transform printer, the chances are your printer will align overlays a little differently.
The solution is to tell CoolSpools that the spooled file was developed for printing on a Host Print Transform (HPT) printer. CoolSpools will then implement a slightly different set of rules for overlay positioning. You do that by naming your HPT printer on the PRTDEV parameter of the CVTSPLPDF command etc., for example:
CVTSPLPDF ... PRTDEV(MY_HPT_PRT)...
Another option is to use:
CVTSPLPDF ... PRTDEV(*HPT)...
In this case CoolSpools will emulate a generic Host Print Transform device.
This will also allow CoolSpools to examine the printer device description and derive certain attributes from the model type of the printer.
Set the page size and orientation
The PAGESIZE parameter is used to specify the size and orientation of the page to be used.
The default value for this parameter is *CALC. CoolSpools will assume a paper size based on the country code of the current job. Letter paper will be assumed if the country code is US (USA) or CA (Canada), otherwise A4 paper will be assumed. The orientation will be derived from the spooled file attributes.
CVTSPLPDF ... PAGESIZE(*CALC)
To specify the page size and orientation.
CVTSPLPDF ...PAGESIZE(*A4 *PORTRAIT)
It is important to note that when specifying the orientation for a page which will be rotated, you should specify the orientation of the un-rotated page. For example, if your report is printed in landscape mode on an A4 printer by means of page rotation, you should specify PAGESIZE(*A4*PORTRAIT), not PAGESIZE(*A4 *LANDSCAPE). This is because, in reality, the spooled file orientation is portrait, but text is printed rotated through 90 degrees to give the effect of landscape printing.
CoolSpools attempts to duplicate the printed output from the spool file in the resulting PDF. If your spooled file has the attribute PAGRTT(*AUTO), PAGRTT(*COR) or PAGRTT(*DEVD), automatic page rotation will occur when the spooled file is printed on a printer and the spooled file does not fit on the page in its standard orientation. For example, if the attributes of your spooled file indicate that it is 132 columns wide at 10 CPI and 66 lines long at 6 LPI (i.e. 13.2 inches by 11 inches), and you print it to a printer which uses letter or A4 paper, the spooled file is too large to fit on the paper. Your printer will automatically reduce the size of the spooled file data (COR) and rotate the spooled file data (auto-rotation) in order to make it fit the paper.
If you are having difficulty getting the page in the correct orientated you could use the PAGEPTION parameter to control which, if any, of these attributes are to be used. PAGEOPTION(*NO) stops auto-rotation and COR being applied and allows you take control of the PDF page size and orientation.
Adjusting margins
The MARGINS parameter allows you to specify additional margins or make adjustments to the alignment of text within the spooled file. If no value is specified on this parameter, CoolSpools will reproduce the margins defined in the spooled file and align text exactly as specified in the printer data stream, which may not necessarily be the way the data appears on the page when printedfrom your printer. You can use this parameter to make slight adjustments to try to ensure that your PDF reproduces the appearance of the printed page as closely as possible.
The units of measure for the margin elements of the parameters can be set to *MM (Millimetres), *INCH (Inch) or *CM (Centimetres). The default is millimetres.
Elements 1 and 2, Left and Top margins.
If your printer has its margins set differently from the norm, CoolSpools can't know about that. You may need to adjust the page margins slightly using the MARGINS parameter to get your overlay to line up.
For example, this will move the text 10mm down the page.
CVTSPLPDF ... MARGINS(0 10)
Elements 3 and 4, Overlays Left and Top of the MARGIN() parameter allow you to define an additional margin or shift for overlays only in the PDF.
Text, images and other items that are held in overlays will be shifted horizontally and/or vertically by the amount you specify on these parameters. A positive value will cause data to shift to the right and a negative value will case data to shift to the right.
This may be useful where the PDF you create with the default parameters appears to have the overlays slightly misaligned from the other content of the spooled file. This can occur, for example, where your printer is for some reason positioning the overlay differently from what would be expected based on the instructions contained in the printer data stream alone (perhaps because data is falling in the no-print border and could not otherwise be printed), and you have programmed your application in such a way as to produce the correct results on that particular printer.
Please note that if the spooled file is rotated, the term "left" refers to the page prior to rotation, in other words the shift may appear at the top, bottom or on the right, depending on the angle through which the page is rotated.
This will leave the text in position but move the overlay 7mm to the left.
CVTSPLPDF ... MARGINS(0 0 7 0 *CALC *CALC *MM)
If you are having difficulty getting the alignment correct, it can be useful to remove all margins to give you a known starting point.
CVTSPLPDF ... MARGINS(0 0 0 0 0 0)
Also, if, due to the rotation of the page, you do not sure which direction is the Left (or Top) use CVTSPLPDF ... MARGINS(20 0 0 0 0 0). The movement of the text should be obvious and give you an indication of the scale and direction of adjustment that is required.
Spool file too wide for the PDF page
There are several methods that can be used to adjust the width.
1. Change the Characters and Lines per inch.
This example changes the CPI to 12 and 8 LPI.
CVTSPLPDF ... TEXT(*OUTPUT *ENVVAR 12 8)
2. Let CoolSpools calculate a scaling factor which will fit the spooled file contents to the paper size and orientation selected on the PAGESIZE parameter.
CVTSPLPDF ... PAGESIZE(*A4 *LANDSCAPE) PAGEOPTION(*NO *FITPAGE *FITPAGE)
3. Specify scaling factors. This will take some trial and error to find the best fit.
CVTSPLPDF ... PAGEOPTION(*NO .60 .65)
4. Change the font size.
This example will be produce a PDF with all text having a point size of 8.
CVTSPLPDF ... FONT(*MAP 8 *ALL)
Change the Font
The 'standard' fonts available in CoolSpools are Courier, Helvetica and Times New Roman these are the base PDF fonts. CoolSpools maps iSeries fonts to an equivalent PC font from the PDF basic font set. This option will minimize the size of the PDF file created, but the appearance of the text in the PDF file may not necessarily exactly reproduce the appearance of the text in the iSeries spooled file when printed, but will normally be very close to it.
The FONT parameter allows you to specify which of the ‘standard’ base PDF fonts you wish to use. Using CVTSPLPDF ... FONT(*TIMES) Times Roman font will be used. CVTSPLPDF ... FONT(*TIMES 8) is similar but the text will Time Roman point size 8.
Using the CVTFONTID parameter gives you close control over how fonts that are identified by a font number (e.g. by means of the DDS FONT keyword or the FONT parameter of the CRTPRTF command) are processed when your spooled file is converted.
The base PDF fonts will not require embedding in the PDF. If other fonts are to be used you should use the FONT(*EMBED) parameter which will result in a larger PDF file.
This method can be useful when a non-uniform width font is specified in the spool file, for example Helvetica. You may find the headings and data in the resulting PDF are not aligned correctly.
This example is replacing Helvetica with ‘BOOKMASTER LATIN1-roman med’ with a point size of 7. Note, due to the fact this is not a standard PDF font it is to be embedded in the PDF.
CVTSPLPDF ... FONT(*EMBED *SCALE *ALL) CVTFONTID(((34123) ('/QSYS.LIB/FONTS.LIB/CZB200.FNTRSC' 7)))
CoolSpools will output information messages to the job log regarding fonts, etc. While you are adjusting the appearance of a PDF, you may find it useful to review the job log. For instance, the message ‘Helvetica-Bold 9.00-point substituted for font id 34123.’ indicates the font id to be used in the CVTFONTID parameter.
To determine which fonts are installed on your iSeries use the command
WRKFNTRSC FNTRSC(*ALL/*ALL) OBJATR(FNTCHRSET)
There is an helpdesk article which lists the characteristics of fonts and can be found at http://www.ariadnesoftware.co.uk/support/knowledgebase.php?article=68
If you cannot get the required result
1. Save your spooled file using the CoolSpools command
SAVSPLF FROMFILE(yourSpoolFile)
TOSTMF(/yourSpoolFile.spl)
JOB(JOB...)
SAVSPLRSC(*YES V5R4M0)
Note: the file extension on the TOSTMF. The helpdesk portal restricts which extensions are allowed.
2. Create a ticket on the CoolSpools Helpdesk portal and attach the file created above. It would also be useful to include an example of the PDF and the CVTSPLPDF command string you have used.
The CoolSpools Helpdesk portal can be found at:
http://www.ariadnesoftware.co.uk/support/