Adding and Configuring Fonts

You can add and configure PostScript Type 1 fonts to significantly expand your options for displaying and printing PS and PDF reports, beyond 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.

How FOCUS Uses Type 1 Fonts

FOCUS 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.

When you execute a report and specify one of these formats as your display format, FOCUS retrieves the data and begins to format the report. Fonts and images specified in the StyleSheet must be available to FOCUS to create the output file. It reads the font information from the font files and embeds that information into the document. The font itself is stored on z/OS.

To ensure that FOCUS 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 FOCUS.
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. FOCUS uses this information to lay out the report on the page. The three built-in fonts also have AFM files, which are distributed with FOCUS. However, these fonts do not require font files, since the fonts are built into 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 FOCUS. You must use the AFM file.
FOCUS Font Map files. These configuration files map the name of a font to the appropriate font metrics and font files (AFM and PFB or PFA). The mapping determines which actual font is used when you specify a font using the FONT attribute in a FOCUS StyleSheet. For example, if your StyleSheet contains the following declaration, FOCUS 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, $
```

Starting with Version 7.7, the separate font map files formerly used for each output format (such as PDF and PS) have been consolidated into two files in a new, XML-based format:

The default font map file, fontmap.xml, contains the font definitions for all output formats that are supported with FOCUS, 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 topics describe how to add your fonts to this file.

The user font map should be in a data set concatenated in front of the distributed ERRORS libraries so it is searched before the default font map. Then font definitions in the user map will override definitions of the same font in the default map.

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 FOCUS.

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.

Top of page

Procedure: How to Configure Type 1 PostScript Fonts

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

Copy the AFM (font metrics) file into a PDS allocated to DDNAME ERRORS in the FOCUS JCL or CLIST. 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.
You can use either PFB (binary) fonts or PFA (ASCII) fonts:
- If you are using PFB (binary) fonts, create a partitioned data set, put the PFB file in it (for example, using FTP in BINARY mode), and allocate this data set to DDNAME PFB.
  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.
- If you are using PFA (ASCII) font files, create a PDS (separate from the one you use for PFB fonts), put the PFA file in it (for example, using FTP in regular, ASCII mode), and allocate this data set to DDNAME PFA. 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 FOCUS which PDS to search for the specified member name.
The user font map file is in member FONTUSER in a data set allocated to DDNAME ERRORS. Using a text editor, add your font definition to the user font map using the syntax described in How to Add Fonts to the Font Map.

Top of page

Syntax: How to Add Fonts to the Font Map

Starting with Version 7.7, the font map file has changed to a more compact XML-based syntax. A major difference from previous releases is that there is now only a single font map file for all output formats, not separate files for PDF and PostScript as before. Type 1 PostScript fonts can now be configured for both PDF and PostScript report formats by modifying a single user font map file, as described in this section.

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 example will use the family name Garamond.

The XML font map syntax uses two XML tags, <family> and <font>, to represent this structure. 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 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 (the text after the "=" 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:
```

```
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: minus sign (-), underscore (_), and blank, and 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 FOCUS obtains from the mapped AFM file) or the font file name.

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. The name refers to a member in a PDS allocated to DDNAME ERRORS. For information about file locations, see How to Configure Type 1 PostScript Fonts.
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 "PFA" or "PFB".
fontfile. This attribute specifies the name of the PFB or PFA file that contains the font itself. As with metricsfile, the value specifies a member in the appropriate PDS (the fonttype attribute specifies the type).

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. These tags are essential to the XML font map syntax and should not be modified. In particular, the <when> tag allows the same font mappings to be used for both PDF and PostScript reports.

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>

Top of page

Example: FOCUS StyleSheet Declaration

Once the font map files have been set up, the newly mapped fonts can be used in a FOCUS 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.

Top of page

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.

Top of page

Reference: The FOCUS Default Font Map

Since the user font map is searched before the FOCUS 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 FOCUS by examining the default font map file.

It is in the FONTMAP member of a partitioned data set allocated to DDNAME ERRORS. Unlike the user font map file, this file has separate sections containing definitions for PS, PDF and DHTML formats. (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.

AFM files for the default fonts are also members of a PDS allocated to DDNAME ERRORS.