Reporting Language > Choosing a Display Format > Using Print Display Formats: PDF, PS

Using Print Display Formats: PDF, PS

Topics:

PDF (Adobe Acrobat Portable Document Format) is most often used to distribute and share electronic documents through the web. It is especially useful if you want a report to maintain its presentation and layout regardless of a browser or printer type. For details, see Using PDF Display Format.

PS (PostScript format), a print-oriented page description language, is most often used to send a report directly to a printer. While used less frequently as an online display format, you can display PS report output on your monitor before printing it. For details, see Using PostScript (PS) Display Format.

Using PDF Display Format

Topics:

You can display a report as a PDF document. PDF (Adobe Acrobat Portable Document Format) supports most StyleSheet attributes, allowing for full report formatting. The wide range of StyleSheet features supported for PDF are described throughout this documentation.

PDF prints and displays a document consistently, regardless of the application software, hardware, and operating system used to create or display the document.

The report opens in Adobe Acrobat or Acrobat Reader within a web browser. To display a PDF report, a computer must have Adobe Acrobat Reader installed. For free downloads of Acrobat Reader, go to http://www.adobe.com.

Limit: Adobe Acrobat PDF format limits the number of pages, hyperlinks, and images in a document. For information about what limits this creates for a report in PDF format, see Saving and Reusing Your Report Output.

Other print-oriented display formats. You can also display a report as a PostScript document. For more information, see Using PostScript (PS) Display Format.

Displaying Watermarks in PDF Output

Topics:

Reference:

Watermarks are images or text strings that are placed on the bottom layer of a document and displayed through the transparent layered content.

WebFOCUS backcolor does not support transparency. Therefore, standard images placed below it on the page may be obscured. To resolve this, in PDF reports, WebFOCUS mirrors the approach taken by standard printers, and places an opaque image on the top of the document layers. With this approach, the layers of the document will be visible beneath the transparent watermark image.

Watermark images are provided by the report developer. When creating a transparent image, the image needs to be created in GIF format with a transparent background.

Reference: Inserting Images in PDF Reports With Backcolor

Watermarks are supported for PDF output in compound reports and in single TABLE requests. Each document supports a single active watermark image. This image is designated as the watermark image, by defining the placement order within the Z-INDEX attribute.

The first image with a Z-INDEX value will be considered the active watermark for the current document. Any subsequent images, defined with style sheet attributes for Z-INDEX or OPACITY, will be displayed as standard WebFOCUS images.

Watermark images are designated by defining the following attributes in the style sheet for the transparent GIF.

Z-INDEX=TOP

Designates that the image is to be handled as a watermark image and should always be placed on top of all other objects on the page. This value will be respected as the topmost layer and will be supported with other layers in future releases.

OPACITY=n

Where n represents the percent (%) of OPACITY to be applied to the image. The greater the OPACITY, the less transparent the image. Less of the underlying report will be visible below the image. The value for n can be any number from 0 through 100. If a value is not specified, it defaults to 100%, presenting a fully opaque image.

Within a single TABLE request: 

TYPE=<REPORT|HEADING>, OBJECT=IMAGE, IMAGE=<image.gif>,
Z-INDEX=TOP, OPACITY=15, POSITION=(.25 .25), DIMENSION=(8 10.5),$

Within compound syntax:

On Page Master

PAGELAYOUT=ALL, NAME='Page Master', $
OBJECT=IMAGE, IMAGE= internalonlyport.GIF, Z-INDEX=TOP, OPACITY=15,
POSITION=(.25 .25), DIMENSION=(8 10.5),$

On Page Layout

PAGELAYOUT=1, NAME='Page Layout1', $
OBJECT=IMAGE, IMAGE= internalonlyport.GIF, Z-INDEX=TOP, OPACITY=15,
POSITION=(.25 .25), DIMENSION=(8 10.5),$
Example: Inserting Transparent Images Into a PDF Report

The following request against the GGSALES data source places the coffee image (coffee.gif) on the page and layers the watermark image (internalonlyport.gif) on top. These images are displayed on every page of the report. 

TABLE FILE GGSALES
SUM
     GGSALES.SALES01.DOLLARS/D12CM
     GGSALES.SALES01.UNITS/D12C
     GGSALES.SALES01.BUDDOLLARS/D12CM
     GGSALES.SALES01.BUDUNITS/D12C
BY GGSALES.SALES01.REGION
BY GGSALES.SALES01.CATEGORY
BY GGSALES.SALES01.PRODUCT
HEADING
"Gotham Grinds"
"Product Sales By Region"
ON TABLE SET PAGE-NUM NOLEAD
ON TABLE NOTOTAL
ON TABLE PCHOLD FORMAT PDF
ON TABLE SET HTMLCSS ON
ON TABLE SET STYLE *
   INCLUDE = endeflt,
   TOPMARGIN=.5,
   BOTTOMMARGIN=.5,
   LEFTMARGIN=1,
   RIGHTMARGIN=1,
$
TYPE=REPORT,
    OBJECT=IMAGE,
    IMAGE=internalonlyport.gif,
    POSITION=(+0.70000 +0.70000), 
    SIZE=(7 7.5),
    Z-INDEX=TOP, OPACITY=15,  
$
TYPE=REPORT,
    OBJECT=IMAGE,
    IMAGE=coffee.gif,
    POSITION=(+1.0 +0.5),
    SIZE=(.5 .5),
$ENDSTYLE
END

The output is:

Features Supported

The following core PDF features are supported with watermarks:

  • Standard TABLE requests, including reports with paneling
  • Compound report (MERGE=OFF)
  • Coordinated compound report (MERGE=ON)
  • Old compound syntax (OPEN/CLOSE)
  • Drilldown
  • Drillthrough
  • Bookmarks
  • Borders/backcolor

Limits

  • OPACITY must be between 0 and 100, inclusive.
  • A single watermark image is supported for a single document.

Usage Notes

  • For new compound syntax, the first watermark image found in the syntax will be used for the report. Any other watermark images found in the code will be ignored or displayed as standard WebFOCUS images.
  • For old compound syntax, the watermark image must be in the first report. If it is not in the first report, a FOC3362 message is generated.
  • The embedded PDF viewer for a browser may not display NLS characters correctly. If NLS characters do not display correctly, use font embedding, as described in Adding PostScript Type 1 Fonts for PS and PDF Formats, or configure your browser to use Adobe Reader.

Using PostScript (PS) Display Format

You can display a report as a PostScript document. PostScript (format PS) is a print-oriented page description language. As a display format, it may be helpful if you wish to see report output on your monitor before printing it using PostScript.

To display a PostScript report, a computer must have a third-party PostScript application installed, such as GSview (a graphical interface for Ghostscript).

If you are sending a PS report to a printer from , you can select the size of the paper on which to print the output. The PostScript code that is generated works on PS printers that support Language Level 2 or above. It is ignored, without harmful effects, on Level 1 printers. This capability is only supported for the PostScript format.

Other print-oriented display formats. You can also display a report as a PDF document. For more information, see Using PDF Display Format.

Font Support

Topics:

Reference:

You can add and configure PostScript Type 1 fonts to significantly expand your options for displaying and printing PS and PDF reports, beyond those provided by the basic set of fonts distributed with Adobe Reader. Thousands of PostScript fonts are available to make your reports more stylish and useful, including some that support symbols and bar codes.

The font map files for Type 1 fonts are stored as XML files (fontmap.xml and fontuser.xml). All font mappings in these files are used for both PDF and PostScript report output.

The font definitions for DHTML also cover PowerPoint (PPT and PPTX). For XLSX, you can define a new default font in the fontuser.xml file. This allows ease in customizing the look and feel of XLSX workbooks. WebFOCUS uses Arial as the default font. However, you can change the default font to match the Microsoft Office standard font, Calibri, or your corporate standard.

Reference: Support for the Symbol Font

To use the Symbol font, specify font=symbol in your StyleSheet:

  • Some versions of Firefox 3 do not support the Symbol font and will substitute it with another font. For information about Firefox support for the Symbol font, refer to Firefox sources.
  • The Euro character displays in PDF output because the Adobe Symbol character set includes the Euro character.
  • The Euro character does not display in DHTML, PPT, and PPTX report output because the Windows Symbol character set does not include the Euro character.
  • The following style options can be rendered with the Symbol font:
    • DHTML, PPT, and PPTX support style=normal, bold, italic, and bold+italic.
    • PDF supports only style=normal. Any other style specified in the StyleSheet will be mapped to normal.

How Uses Type 1 Fonts

generates a PDF or PS document from scratch. In order to do that, it must physically embed all the objects it displays or prints, including images and fonts, in the document itself.

To ensure that can locate the required information, you must define and map it in the following files:

  • Font file, usually a PFB (Printer Font Binary) file. This file contains the information about the shape to draw for each character of the font. The information in the font file is scalable, which means that a single font file can be used to generate characters of any size. Note, however, that bold and italic variations of the typeface are separate fonts. An alternative ASCII format, PFA, can also be used by .
  • Adobe Font Metrics (AFM) file. This file is distributed with all Adobe fonts. It contains information about the size of each character in each font. uses this information to lay out the report on the page. Note that the three built-in fonts also have AFM files, which are distributed with . However, these fonts do not require font files, since the fonts are built in to Adobe Reader.

    Note: A Printer Font Metrics (PFM) file is also available. This file is used by applications such as Adobe Reader for laying out text, however it is not supported by . You must use the AFM file.

  • These configuration files map the name of a font to the appropriate font metrics and font files . The mapping determines which actual font is used when you specify a font using the FONT attribute in a StyleSheet. For example, if your StyleSheet contains the following declaration, will search the font map for a font mapping with a matching name and style, and use the font specified by the mapping:
    TYPE=REPORT, FONT=HELVETICA, STYLE=ITALIC, $

There are two files uses for mapping fonts, both in an XML-based format:

  • The default font map file, fontmap.xml, contains the font definitions for all output formats that are supported with , as originally installed. Users should not modify this file.
  • The user font map file, fontuser.xml, contains font definitions added by the user. The following sections describe how to add your fonts to this file.

You can also use a variety of utilities to convert Windows True Type fonts (such as Arial and Tahoma) into Type 1 fonts. Verify that you are licensed for this type of font use. Then, after you convert them, you can define and map these fonts for use by .

One such utility is TTF2PT1.

For information about the Windows version, go to:

http://gnuwin32.sourceforge.net/packages/ttf2pt1.htm

Adding PostScript Type 1 Fonts for PS and PDF Formats

How to:

Reference:

This section describes how to add PostScript type 1 fonts to the fontuser.xml file.

Procedure: How to Configure Type 1 PostScript Fonts on z/OS

After you have located the font files you wish to add, you can configure to use one or more Type 1 fonts.

  1. Copy the AFM (font metrics) file into the PDS allocated to DDNAME . You can copy this file from another machine using FTP in standard ASCII (text) mode. The member name of the AFM file in this PDS will match the metricsfile value in the font map file.

    Note: If the Windows font file names contain underscore characters or are longer than eight characters, you must rename them, since these are not valid for z/OS member names.

  2. You can use either PFB (binary) fonts or PFA (ASCII) fonts:
    • .

      This PDS should be created with the following DCB attributes: 

      RECFM: VB    LRECL: 1028    BLKSIZE: 27998

      The member name in this PDS should match the fontfile name in the font map file.

      If you copy the PFB font file into the PDS using FTP, you must use BINARY mode. The member name of the PFB file in this PDS will match the fontfile value in the font map file.

    • . This PDS should be created with the following DCB attributes:
      RECFM: VB    LRECL: 2044    BLKSIZE: 27998

      The member name in this PDS should match the fontfile value in the font map file. Note that you can use PFB and PFA files simultaneously. The fonttype attribute in the font map file (PFB or PFA) tells which PDS to search for the specified member name.

  3. Using a text editor, add your font definition to the user font map using the syntax described in Add Fonts to the Font Map.

Syntax: How to Add Fonts to the Font Map

The Type 1 PostScript fonts used with the PostScript and PDF output formats use separate font files for each variant of the font: normal, bold, italic, and bold-italic. This grouping of related fonts is called a font family.

The XML font map syntax uses two XML tags, <family> and <font>, to represent this structure. The example uses the family name Garamond. For example: 

<family name="garamond">
  <font style="normal"
        metricsfile="gdrg" fontfile="gdrg" fonttype="PFB" />
  <font style="bold"
        metricsfile="gdb"  fontfile="gdb" fonttype="PFB" />
  <font style="italic"
        metricsfile="gdi"  fontfile="gdi" fonttype="PFB" />
  <font style="bold+italic"
        metricsfile="gdbi" fontfile="gdbi" fonttype="PFB" />
</family>

The following example uses the family name otf. For example:

<family name="otf">
  <font style="normal"
        metricsfile="otfn"  fontfile="otfn" fonttype="OTF" />
  <font style="bold"
        metricsfile="otfb"  fontfile="otfb" fonttype="OTF" />
  <font style="italic"
        metricsfile="otfi"  fontfile="otfi" fonttype="OTF" />
  <font style="bold+italic"
        metricsfile="otfbi" fontfile="otfbi" fonttype="OTF" />
</family>

The basics of the XML syntax are:

  • Tag names (such as family and font) and attribute names (such as style or metricsfile) must be in lowercase. Attribute values, such as font file names, are case-insensitive.
  • Attribute values, which is the text after the equal sign (=), must be in double quotation marks (for example, "bold")
  • Elements that have no explicit end-tag must end with />. (For example, the family tag has the closing tag </family>, but the font tag has no closing tag, so it ends with />.)
  • Comments are enclosed in special delimiters:
    <!-- This is a comment -->
  • Line breaks may be placed between attribute-value pairs.

A more complete description of XML syntax can be found here:

http://en.wikipedia.org/wiki/Xml

The family element

The family element specifies the name of a font family. This family name, specified in the name attribute of the family element, is the name by which the font will be referenced in a StyleSheet. It corresponds to the value of the FONT attribute in the StyleSheet. The end-tag </family> closes the family element, and any number of additional family elements may follow.

Font family names should be composed of letters (A-Z, a-z), digits, and limited special characters, such as a minus sign (-), underscore (_), and blank. Font family names should have a maximum length of 40 characters. Since the font name is only a reference to a mapping in the font map, it does not need to be related to the actual name of the font (which obtains from the mapped AFM file) or the file name of the font.

Font elements

Nested within each family element are one or more font elements that specify the font files for each font in the family. For example, there may be one font element for the font Garamond Regular (normal), one for Garamond Italic (italic). Since a font element has no child elements, it is closed with "/>".

The actual name of the font as used in the PDF or PostScript document is taken from the font metric file.

Fonts defined in the user font file (fontuser.xml) can override default font definitions in fontmap.xml. Thus, you should be careful to choose family names that do not conflict with existing definitions, unless you actually wish to override these definitions (which should generally not be done).

Each font element contains the following attributes:

  • style: This attribute specifies the style of the font and corresponds to the STYLE attribute in the StyleSheet. The allowed values are "normal", "bold", "italic", and "bold+italic". For example, the font defined in the following bold italic font element:
    <font style="bold+italic" metricsfile="gdbi" fontfile="gdbi" fonttype="PFB" />

    could be referenced in the StyleSheet like this: 

    TYPE=REPORT, FONT=GARAMOND, STYLE=BOLD+ITALIC, $

    Although most fonts have a font file for each of the four styles, some specialized fonts such as bar code fonts might only have a single style (usually "normal"). Only the styles that exist for a particular font need to be specified in the font map file.

    The actual names of the fonts may vary. Some fonts may be called "oblique" rather than "italic", or "heavy" rather than "bold". However, the font map and StyleSheet always use the keywords "normal", "bold", "italic" and "bold+italic".

  • metricsfile: This attribute specifies the name of the Adobe Font Metrics (AFM) file that provides the measurements of the font. You should only use the base name of the file (for example, "gdrg", not "gdrg.afm"). For information about file locations, see How to Configure Type 1 PostScript Fonts on z/OS Under PDS Deployment.

    File names should be composed of letters and numbers, and should not contain blanks.

  • fonttype: This attribute specifies the type of the font file. The allowed values are .
  • fontfile: This attribute specifies the name of the PFB or PFA file that contains the font itself. As with metricsfile, the value specifies only the base file name (the fonttype attribute specifies the type). On Windows and UNIX, the file is assumed to have the extension .pfb for binary (PFB) font files or .pfa for ASCII (PFA) font files, and should reside in the same directory as the AFM files (wfs/etc). On z/OS with PDS deployment, the name refers to a member in the appropriate PDS.

Additional items of XML syntax include the XML header on the first line of the file and the <fontmap> and <when> elements that enclose all of the family elements. The <when> tag allows the same font mappings to be used for both PDF and PostScript reports across output formats. These can include PDF, PS, and DHTML. PPT and PPTX formats will use fonts specified for DHTML. If no <when> is specified, the font will be available for all formats.

The following is a complete example of a user font map: 

<?xml version="1.0" encoding="UTF-8" ?>
<!-- Example of a user font map file with two font families. -->
<fontmap version="1">
    <when format="PDF PS">
        <family name="garamond">
            <font style="normal"
                  metricsfile="gdrg" fontfile="gdrg" fonttype="PFB" />
            <font style="bold"
                  metricsfile="gdb"  fontfile="gdb"  fonttype="PFB" />
            <font style="italic"
                  metricsfile="gdi"  fontfile="gdi"  fonttype="PFB" />
            <font style="bold+italic"
                  metricsfile="gdbi" fontfile="gdbi" fonttype="PFB" />
        </family>
        <!-- This font only has a "normal" style, others omitted. -->
        <family name="ocra">
            <font style="normal"
                  metricsfile="ocra" fontfile="ocra" fonttype="PFB" />
        </family>
    </when>
</fontmap>
Example: StyleSheet Declaration

Once the font map files have been set up, the newly mapped fonts can be used in a StyleSheet. For example, to use the Garamond fonts: 

ON TABLE SET STYLE *
type=report, font=garamond, size=12, $
type=title, font=garamond, style=bold, color=blue, $
ENDSTYLE

Since the style attribute has been omitted for the report font in the StyleSheet, it defaults to normal. Attributes such as size and color can also be applied.

Reference: Editing the Font Map File

There is a byte order mark (BOM) at the beginning of the user font map file (fontuser.xml), which must be preserved for this file to be read correctly.

If you are using a Unicode-aware editor, such as Notepad on Windows, to edit the file, the BOM will not be visible, but you can preserve it by making sure that you select an encoding of UTF-8 in the Save-As dialog. In most other editors, such as the ISPF editor under z/OS, the BOM will display as three or four strange-looking characters at the beginning of the file. As long as you do not delete or modify these characters, the BOM will be preserved.

Reference: The Default Font Map

Since the user font map is searched before the default font map, font definitions in the user font map file will override mappings of the same font in the default font map file. Since you usually would not want to override existing font mappings, you can check which font names are already used by by examining the default font map file.

Unlike the user font map file, this file has separate sections containing definitions for PS, PDF, and DHTML formats.

Note: The DHTML mappings are used for the DHTML and PowerPoint output formats, which do not support user-added fonts.

Since the font mappings in the default font map file are for fonts that are already assumed to exist on the user machines (for example, built-in Adobe Reader fonts, standard PostScript printer fonts, or standard Windows fonts), they do not reference font files, only font metrics files. Fonts provided by the user should reference both font files and metrics files.

Procedure: How to Define a Default Font in the Font Map

An individual default font can be set for each output type and/or language setting within an output type. This setting should be defined in the fontuser.xml file rather than the fontmap.xml file. Fontmap.xml may be updated by a future release installation, so customizations may be lost. Additionally, the settings in fontuser.xml override settings in fontmap.xml.

Note:

  • Fontmap.xml can be found in ..\ibi\srvXX\home\etc\style, where XX is your server release.
  • Fontuser.xml can be found in ..\ibi\srvXX\wfs\etc, where XX is your server release.

To designate the default font use the following steps:

  1. Copy the selected font entry from frontmap.xml to fontuser xml.
    1. Within fontmap.xml, find the entry for the font family within the desired output format to be designated as the default.
    2. Copy the entire entry into the appropriate format area within fontuser.xml.
  2. In fontuser.xml, within the entry for the font to be designated as the default font and style, add the following attribute: 
    default="yes"

    For example, the following code defines the default fonts to be Helvetica bold for PDF, Calibri for XLSX, and Arial Italic for DHTML: 

    <fontmap version="1">
<when format="PDF PS">
  <family name="Helvetica" htmlfont="Arial">
     <font style="normal" metricsfile="pdhelv"   />
     <font style="bold"   metricsfile="pdhelvb"  default="yes"  />
     <font style="italic"  metricsfile="pdhelvi"  />
     <font style="bold+italic" metricsfile="pdhelvbi" />
  </family>
</when>
<when format="XLSX">
  <family name="Calibri" htmlfont="Calibri">
     <font style="normal"      metricsfile="ttcali"  default="yes" />
     <font style="bold"        metricsfile="ttcalib"  />
     <font style="italic"      metricsfile="ttcalii"  />
     <font style="bold+italic" metricsfile="ttcalibi" />
  </family>
</when>
<when format="DHTML">
  <family name="Arial">
     <font style="normal"  metricsfile="ttarial"  />
     <font style="bold"    metricsfile="ttarialb" />
     <font style="italic"  metricsfile="ttariali" default="yes"  />
     <font style="bold+italic" metricsfile="ttariabi" />
  </family>
</when>
</fontmap>

    If multiple fonts in a font map family, such as PDF, have the default="yes" attribute, the last font with that attribute becomes the default font. Fonts in fontuser.xml are processed after those in fontmap.xml, so a default font set in fontuser.xml can override the one set in fontmap.xml.

    A default font set in the PDF section of the font map does not affect a default in the DHTML section, and a default for one specific language does not override the default for other languages.

Creating PDF Files on z/OS for Use With UNIX Systems

How to:

Reference:

PDF files created with HOLD FORMAT PDF present a challenge if you work in a z/OS environment and use UNIX-based systems as the server for Adobe or as an intermediate transfer point.

The end of each PDF file has a table containing the byte offset, including line termination characters, of each PDF object in the file. The offsets indicate that each line is terminated by two characters, a carriage return and a line feed, which is the standard Windows text file format. However, records in a UNIX text file are terminated by one character, a line feed only. When using default settings, the offsets in a PDF file will be incorrect, causing an error when Acrobat attempts to open the file. If the file is then transferred in BINARY mode to Windows, it cannot be opened in Acrobat for Windows, as the carriage-return character was not inserted.

One solution has been to transfer the file to the UNIX system in text mode and then transfer in text mode to the Windows system, as the carriage return is added by the transfer facility when transferring to Windows.

If that is not possible or desirable, you can use the SET PDFLINETERM=SPACE command to facilitate binary transfer to Windows from an ASCII-based UNIX system. This command causes an extra space character to be appended to each record of the PDF output file. This extra space acts as a placeholder for the expected carriage return character and makes the object offsets in the file correct when it is transferred from z/OS to a UNIX system. This enables a UNIX server to open a PDF file in that environment.

Note: A text mode transfer is always required when transferring a text file from a mainframe to any other environment (Windows, ASCII Unix, or EBCDIC Unix).

Syntax: How to Specify Line Termination Characters When Creating a PDF File

In a profile, a FOCEXEC, or from the command line, issue the following command: 

SET PDFLINETERM={STANDARD|SPACE}

In a TABLE request, issue the following command 

ON TABLE SET PDFLINETERM {STANDARD|SPACE}

where:

STANDARD

Creates a PDF file without any extra characters. This file will be a valid PDF file if transferred in text mode to a Windows machine, but not to a UNIX machine. If subsequently transferred from a UNIX machine to a Windows machine in text mode, it will be a valid PDF file on the Windows machine.

SPACE

Creates a PDF file with an extra space character appended to each record. This file will be a valid PDF file if transferred in text mode to a UNIX machine, but not to a Windows machine. If subsequently transferred from an ASCII UNIX machine to a Windows machine in binary mode, it will be a valid PDF file on the Windows machine.

Reference: Required PDFLINETERM Settings Based on Environment

The following chart will assist you in determining the correct setting to use, based on your environment:

Transferring from z/OS to:

SET PDFLINETERM=

EBCDIC UNIX (text transfer)

SPACE

ASCII UNIX (text transfer)

SPACE

ASCII UNIX (text); then to Windows (binary)

SPACE

UNIX (text); then to Windows (text)

STANDARD

Directly to Windows (text)

STANDARD

WebFOCUS

Feedback