IBM WebSphere Host On-Demand Version 10.0

Host Printing Reference

Eighth Edition (March 2006)

This edition applies to Version 10.0 of IBM (R) WebSphere Host On-Demand (program number 5724-I20) and to all subsequent releases and modifications until otherwise indicated in new editions.

(C) Copyright International Business Machines Corporation 1997, 2004. All rights reserved.
Note to U.S. Government Users -- Restricted Rights -- Use, duplication, or disclosure restricted by GSA, ADP Schedule Contract with IBM Corp.

About this book

The Host Printing Reference describes the host printing functions provided by Host On-Demand.

This document is written for application developers and administrators.

The Host Printing Reference is also available both on the product CD-ROM and in the Host On-Demand online Information Center at http://publib.boulder.ibm.com/infocenter/hod9help.

The MySupport feature enables you to personalize your support view and to register to receive weekly e-mail notifications alerting you to new patches, new downloads, and other timely technical support information for IBM products. To register for MySupport, follow the instructions in the Technote found at the following URL: http://www.ibm.com/support/docview.wss?rs=132&context=SS5RCF&uid=swg21168680&loc=en_US&cs=utf-8&lang=en+en

Conventions used in this book

The following typographic conventions are used in the Host Printing Reference:

This graphic is used to highlight notes to the reader.

Introduction to Host Printing (3270)

The Host On-Demand client supports 3270 printing. You can direct a 3270 Logical Unit Type 3 (LU3) or Logical Unit Type 1 (LU1) print data stream to any of the following print destinations:

• To a printer directly attached to the workstation on which the Host On-Demand client is running.
• To a network printer accessible from the workstation.
• To a local file or to a network file accessible from the workstation.

A Host On-Demand 3270 printer session emulates an IBM 3287 printer running in either LU3 or LU1 mode.

Automatic detection of LU type

When you configure a 3270 Printer session, you do not have to specify whether the session uses LU Type 3 or LU Type 1. Instead, the Host On-Demand client automatically detects the LU type when the client connects with the 3270 host.

The term Logical Unit (LU) comes from the Systems Network Architecture (SNA). In a 3270 Printer session, the Host On-Demand client connects with a Telnet server rather than with an SNA server. However, the LU3 or LU1 data stream transmitted by the Telnet server is identical with the LU3 or LU1 data stream transmitted by an SNA server.

Emulation of a 3287 printer

Because the purpose of a Host On-Demand 3270 Printer session is to emulate a 3287 printer, a 3270 Printer session does not offer the same options that you may be used to seeing when you print a document from a word-processing program. In particular, you will find these differences:

• A 3270 Printer session offers relatively few font sizes, because the 3270 print data stream supports only a few values for Characters per inch (10, 12, and 17) and Lines per inch (2, 3, 4, 6, 8).
• A 3270 Printer session has page setup options for control codes that occur in the 3270 print data stream (such as nulls and null lines).

The Printer Setup window (3270)

This section contains background information to help you understand how to configure the Printer Setup window for a 3270 Printer session.

To open the Printer Setup window for a 3270 Printer session, follow these steps:

1. Open the session properties window for a 3270 Printer session.
2. In the left pane, click Printer Setup.

You can also open the Printer Setup window from other contexts (see Printer Setup (3270 Printer session, 5250 Printer session, and 3270 Display session) in the online help). Configuring the Printer Setup window in these contexts is similar to the configuration described here.

Print methods

The Print to listbox at the top of the Printer Setup window offers (depending on the client platform) up to five print methods:

• Windows Printer, with Use Printer Definition Table set to No
• Windows Printer, with Use Printer Definition Table set to Yes
• Other Printer (always uses a Printer Definition Table)
  • On a Windows client, this print method is called Other Printer.
  • On a non-Windows client, this print method is called simply Printer.
• File, with Use Adobe PDF set to No (always uses a Printer Definition Table)
• File, with Use Adobe PDF set to Yes (does not use a Printer Definition Table)

The following sections describe how to use the print methods on the following Host On-Demand client platforms.

• Windows (All 5 print methods are available.)
• UNIX, AIX, Linux (Only 3 print methods are available.)
• OS/2 (Only 3 print methods are available.)

Using the print methods on the Windows platform

The following table shows the print methods available when the Host On-Demand client is running on a Windows platform and summarizes the characteristics associated with each print method:

A. Windows Printer, with Use Printer Definition Table set to No

This is the default print method for the Host On-Demand client running on a Windows platform. To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click Windows Printer.
3. Set Use Printer Definition Table to No.

You can select the Windows printer that you want to use, either a local printer or a network printer. To select a Windows printer:

1. Open the Printer Setup window.
2. To use the default Windows printer, set Choose Windows Printer to Use Default.
3. To select another Windows printer:
   1. Set Choose Windows Printer to Other.
   2. Click Select Printer

You can select a Windows font. To select a Windows font:

1. Open the Page Setup window.
   1. In the session properties window, in the left pane, click Page Setup.
2. Click Select Font.
3. In the Font window, select a font from the Font column.
   • Do not use the Font style and Size settings in the Font window. Even though these settings appear to be enabled, they have no effect on Host On-Demand client printing.

You can easily modify Windows printer properties (such as Portrait or Landscape, Pages Per Sheet, Print Quality, and other properties) using the Windows Print Setup dialog. To modify Windows printer properties:

• Open the Printer Setup window.
• Set Choose Windows Printer to Use Default.
• Click Select Printer.
• In the Print Setup dialog, click Properties.

This print method (Windows Printer, with Use Printer Definition Table set to No) is useful when it is not possible to access the printer without using the Windows printer driver (as is the case with a USB printer or a Windows-only printer) or when a PDT file is not available (as is the case with a PostScript printer).

Because this print method uses Windows Native Printer Interface (WPNI) mode:

• You can print some special characters (such as the euro character) if the characters are present in the Windows font, even if the printer does not have the special characters in its firmware.
• Processing is slower than with print method B.
• The 3270 data stream command TRN (Transparent) may not be processed correctly. If not, use a different print method.

B. Windows Printer, with Use Printer Definition Table to Yes

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click Windows Printer.
3. Set Use Printer Definition Table to Yes.
4. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

You can select the Windows printer that you want to use, either a local printer or a network printer. To select a Windows printer:

1. Open the Printer Setup window.
2. To use the default Windows printer, set Choose Windows Printer to Use Default.
3. To select another Windows printer:
   1. Set Choose Windows Printer to Other.
   2. Click Select Printer

Because this print method uses Windows Spooler Interface (WSI) mode:

• You cannot print some special characters (such as the euro character) unless the printer has the special characters in its firmware.
• Processing is faster than with print method A.

C. Other Printer (always uses a Printer Definition Table)

On non-Windows platforms, this print method is called Printer.

Normally you do not need to use this print method on the Windows platform. It produces the same output as method A or method B, but is less user friendly.

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click Other Printer.
3. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

In the Printer Name field, you can type any one of the following:

• The name of a valid print device (such as LPT1, LPT2, and so on).

  The Host On-Demand client writes the print data stream to the LPT device that you specify. The user is responsible for configuring the client workstation to associate this LPT device with a printer.

• The UNC name of a network printer (such as \\myServer\myPrinter).

  The Host On-Demand client writes the print data stream to the network printer.

• A valid file path and name.

  The Host On-Demand client writes the print data stream to the specified file.

  • If the file path is not included (that is, if only the file name is specified) then the Host On-Demand client writes the print data stream to the specified file name in the browser's working directory.
  • If the file path is a relative path, then the Host On-Demand client applies the relative path to the browser's working directory and the writes the print data stream to the specified file name in that directory.

D. File, with Use Adobe PDF set to No (always uses a Printer Definition Table)

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click File.
3. Set Use Adobe PDF to No.
4. In the File Path and Name field, type a valid file path and name.
5. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

For the file path and name, see Specifying a File Path and Name.

You can also use the File Path and Name field to specify one or more native console commands to be run after the host print job completes (see Running external commands after host print jobs in the online help).

This print method is useful when you do not want to send the print output to a printer immediately. For example:

• You might not have access to a printer; or
• You might want to attach the print output file to an e-mail.

This print method also is useful when if you want to generate print output in a flat ASCII format.

E. File, with Use Adobe PDF set to Yes (does not use a Printer Definition Table)

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click File.
3. Set Use Adobe PDF to Yes.
4. In the File Path and Name field, type a valid file path and name.

The Host On-Demand client transforms the print output to binary data in Adobe PDF format, and writes the binary data into the specified file. The file can be viewed with Adobe Reader version 4.0 or later.

This print method is useful when you want to transform the data to a portable and easily viewable format.

This method does not require a PDT.

Using the print methods on UNIX, AIX, or Linux

The following table shows the print methods available when the Host On-Demand client is running on a UNIX, AIX, or LINUX platform, and summarizes the characteristics associated with each print method:

A. Windows Printer, with Use Printer Definition Table set to No

This print method is not available on UNIX, AIX, or Linux.

B. Windows Printer, with Use Printer Definition Table set to Yes

This print method is not available on UNIX, AIX, or Linux.

C. Printer (always uses a Printer Definition Table)

On Windows platforms, this print method is called Other Printer.

This is the default print method for the Host On-Demand client when it is running on a UNIX, AIX, or Linux platform. To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click Other Printer.
3. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

To send the print output to a printer attached directly to the workstation, you must type a valid device name (such as /dev/lp0) into the Printer Name field. The Host On-Demand client writes the print data stream to the device that you specify.

To send the print output to a network printer, you cannot use this method on UNIX, AIX, or Linux. Instead, use method D.

D. File, with Use Adobe PDF set to No (always uses a Printer Definition Table)

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click File.
3. Set Use Adobe PDF to No.
4. In the File Path and Name field, type a valid file path and name.
5. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

For the file path and name, see Specifying a File Path and Name.

You can also use the File Path and Name field to specify one or more native console commands to be run after the host print job completes (see Running external commands after host print jobs in the online help).

This print method is useful when you do not want to send the print output to a printer immediately. For example:

• You might not have access to a printer; or
• You might want to attach the print output file to an e-mail.

You must also use this method when you want to send print output from an UNIX, AIX, or Linux workstation to an available network printer. Follow these steps:

1. Use the File print method to send the output to a file.
2. From the command prompt, issue the appropriate command to send the file to the network printer. For example, if the name of the file is hprint.000 and the name of the remote printer is prtq1, then you might type:

   lp  -dprtq1  hprint.000

   or

   lp  -Pprtq1  hprint.000

E. File, with Use Adobe PDF set to Yes (does not use a Printer Definition Table)

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click File.
3. Set Use Adobe PDF to Yes.
4. In the File Path and Name field, type a valid file path and name.

The Host On-Demand client transforms the print output to binary data in Adobe PDF format, and writes the binary data into the specified file. The file can be viewed with Adobe Reader version 4.0 or later.

This print method is useful when you want to transform the data to a portable and easily viewable format.

This method does not require a PDT.

Using the print methods on OS/2

The following table shows the print methods available when the Host On-Demand client is running on an OS/2 platform and summarizes the characteristics associated with each print method:

A. Windows Printer, with Use Printer Definition Table set to No

This print method is not available on OS/2.

B. Windows Printer, with Use Printer Definition Table set to Yes

This print method is not available on OS/2.

C. Printer (always uses a Printer Definition Table)

On Windows platforms, this print method is called Other Printer.

This is the default print method for the Host On-Demand client when it is running on an OS/2 platform. To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click Other Printer.
3. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

In the Printer Name field, you can type any one of the following:

• The fully qualified path of the OS/2 printer driver. You have two alternatives here:
  • Specify the correct driver for the directly attached printer, and use basic.hodpdt as the PDT.
    • The printer driver will do basic formatting according to its default settings.
  • Specify the IBMNULL printer driver, and use some other PDT.
    • The formatting is controlled by the PDT.
    • You must use this alternative if you want the PDT to control the format of the print job.
• The UNC name of a network printer (such as \\myServer\myPrinter).

  The Host On-Demand client writes the print data stream to the network printer using the PDT that you specify.

• A local printer device (such as LPT1, LPT2, and so on).

  The Host On-Demand client writes the print data stream to the specified device as an ASCII text file. Normally, you do not want to create this type of output.

D. File, with Use Adobe PDF set to No (always uses a Printer Definition Table)

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click File.
3. Set Use Adobe PDF to No.
4. In the File Path and Name field, type a valid file path and name.
5. Expand the Printer Definition Table listbox and select a PDT.

Before the Host On-Demand client can use this print method, the Host On-Demand administrator must provide a Printer Definition Table (PDT) (see Creating a PDT file ).

For the file path and name, see Specifying a File Path and Name.

You can also use the File Path and Name field to specify one or more native console commands to be run after the host print job completes (see Running external commands after host print jobs in the online help).

This print method is useful when you do not want to send the print output to a printer immediately. For example:

• You might not have access to a printer; or
• You might want to attach the print output file to an e-mail.

E. File, with Use Adobe PDF set to Yes (does not use a Printer Definition Table)

To select this print method:

1. Open the Printer Setup window.
2. Expand the Print to listbox and click File.
3. Set Use Adobe PDF to Yes.
4. In the File Path and Name field, type a valid file path and name.

The Host On-Demand client transforms the print output to binary data in Adobe PDF format, and writes the binary data into the specified file. The file can be viewed with Adobe Reader version 4.0 or later.

This print method is useful when you want to transform the data to a portable and easily viewable format.

This method does not require a PDT.

Print Technologies

The Host On-Demand host print clients (3270 Printer session and 5250 Printer session) use the following three print technologies (or print "modes"):

• Windows Native Printer Interface (WPNI) mode
• Windows Spooler Interface (WSI) mode
• Java File Interface (JFI) mode

The 3270 Display session uses a fourth print technology:

• Java print mode (see Non-Java print mode and Java print mode in the online help)

The following table summarizes the relationships between the five print methods described in the preceding sections and the three print technologies used by host print clients:

The following subsections describe each of the three print technologies (print "modes")

Windows Native Printer Interface mode

This mode is supported by Host On-Demand Version 6.0 and later versions and is available only on clients running a Windows platform.

In this mode, the Host On-Demand client sends the print data stream to the printer by making Graphics Device Interface (GDI) API calls to the Windows printer driver for the selected printer via the Java Native Interface (JNI).

Because the Host On-Demand client is communicating with the Windows printer driver, this mode is useful:

• When it is not possible to access the printer in any other way (as is the case with a USB printer or a Windows-only printer).
• When a PDT file is not available (as is the case with a PostScript printer).

Because the Host On-Demand client communicates with the Windows printer driver:

• You can select a Windows printer and a Windows font, and you can modify Windows printer properties using the Windows Print Setup dialog.
• Processing is slower, because there is more overhead.
• This mode may not be able to handle the 3270 data stream command TRN (Transparent).

The Windows Native Printing mode uses two Windows native library files (hodprint.dll and hodprinterdriver.dll), which are automatically installed to your local file system. The directory where those files are installed varies depending on the Windows platform and the browser you are using.

If you are using Netscape Version 4.x (for example, Version 4.75), Host On-Demand will additionally install the following three Java class files: WinPrint.class, NativePrinter.class, and HODPrinterDriver.class.

Windows Spooler Interface mode

This mode is supported by Host On-Demand Version 6.0 and later versions and is available only on clients running a Windows platform.

In this mode, the Host On-Demand client:

1. Uses a Printer Definition Table (PDT) to transform the 3270 print data stream to a printer data stream that is meaningful to the selected printer.
2. Sends the printer data stream to the printer by calling the Windows Spooler Interface API via the Java Native Interface (JNI).

The use of a Printer Definition Table (PDT) often provides greater flexibility than may be available with Windows Native Printer Interface (WPNI) mode, because the PDT can specify printer data stream features that may not be supported by the Windows printer driver.

The Windows Spooler Interface mode uses two Windows native library files (hodprint.dll and hodspoolermode.dll), which are automatically installed to your local file system. The directory where those files are installed varies depending on the Windows platform and the browser you are using.

If you are using Netscape Version 4.x (for example, Version 4.75), Host On-Demand will additionally install the following three Java class files: WinPrint.class, NativePrinter.class, and HODSpoolerMode.class.

Java File Interface mode

This mode is supported on all Host On-Demand client platforms that support host print.

In this mode the Host On-Demand client:

1. Uses a Printer Definition Table (PDT) to transform the 3270 print data stream to a printer data stream that is meaningful to the printer.
2. Writes the printer data stream to a printer device (such as LPT1, \\myServer\myPrinter, or /dev/lp0) or to a file.

The use of a Printer Definition Table (PDT) provides great flexibility, because the PDT can specify detailed printer data stream features.

Specifying a File Path and Name

When you select to print to a file in the drop-down list of Print To options in the Printer window, you can type the File Path and Name. 

• If you do not type the name of the file, and you select No for Use Adobe PDF and No for Separate Files, Host On-Demand will print to the default file default.prn in the default path determined by Host On-Demand. If you select No for Use Adobe PDF and Yes for Separate Files, Host On-Demand will first print to the default file default.prn.000, next to default.prn.001, and so on in the default path determined by Host On-Demand.
  
• If you do not type the name of the file, and you select Yes for Use Adobe PDF, Host On-Demand will first print to the default file 00000001.pdf, next to 00000002.pdf, and so on in the default path determined by Host On-Demand.
  
• If you do not type the absolute path of the file, Host On-Demand will determine the default file path using the following rules:
  1. If the java.io.tmpdir Java system property is defined, Host On-Demand will use the directory that is specified.
  2. If the java.io.tmpdir Java system property is not defined and the current browser is Internet Explorer, Host On-Demand will use the parent file path of the directory specified in the user.dir Java system property.
  3. If the first two rules do not apply, Host On-Demand will use the directory that the user.home Java system property specifies.
  
  The outcome depends on your operating systems and browser environments. 
  
  In order to avoid ambiguity, specify the file path explicitly. 
  
• On Windows platforms, print output goes to a printer if you enter any valid LPT number or a UNC name (such as \\server_name\printer_name). On AIX and UNIX, print output goes directly to a printer if you enter a device name such as /dev/lp0. If you print to a local port (LPT1), print jobs are formatted by the printer driver like an ASCII text file.

Creating Adobe PDF Files

3270 printer sessions now include the option to print to Adobe PDF files. This feature allows users to view files in a standard Web browser with the Adobe Acrobat plug-in installed. The Advanced Options panel enables the selection of  paper size, paper orientation, and Adobe PDF fonts.

The following table lists all of the supported paper sizes for Adobe PDF files. The default paper size for US English and Canadian locales is Letter. For all other locales, the default paper size is A4. 

Table 5. Supported Paper Sizes

For continuous sheets, the default margin value on all sides (top, bottom, right, and left) is 0. For North American paper (not including continuous sheets), the default margin value is 0.25 inches on all sides. For ISO/Japanese paper, the default margin value is 5 mm on all sides. 

Code pages used in Adobe PDF files

If the specified host code page is not Bidi or DBCS, Host On-Demand uses an internal Windows code page in the generated Adobe PDF file. The following list shows the Windows code pages that are used for specific host code pages:

• 1250 Windows Latin 2 (Central Europe) - 870 and 1153
• 1251 Windows Cyrillic (Slavic) - 1025, 1123, 1154, and 1158
• 1252 Windows Latin 1 (ANSI)- 037, 273, 275, 274, 277, 278, 280, 284, 285, 297, 500, 871, 924, 1047, 1140, 1141, 1142, 1143, 1144, 1145, 1146, 1147, 1148, and 1149
• 1253 Windows Greek - 875
• 1254 Windows Latin 5 (Turkish) - 1026 and 1155
• 1257 Windows Baltic Rim - 1112, 1122, 1156, and 1157

Since Greek host code page 875 and Estonian host code pages 1122 and 1157 have characters that are not included in the Windows code pages above, the following characters cannot be printed:

• 875 Greek Host - 0xA0 and 0xDD
• 1122 and 1157 Estonian Host - 0x42, 0x44-0x46, 0x48, 0x49, 0x52-0x58, 0x62, 0x64-0x66, 0x68, 0x69, 0x72-0x78, 0x8D, 0x9A, 0x9B, 0xAA, 0xAB, 0xAD, 0xB2, 0xBC, 0xCB, 0xCD, 0xDB, 0xDD-0xDF, 0xEB, 0xED, 0xFB, 0xFD, 0xFE

Creating a PDT file

Please note the following definitions:

• A Printer Definition Table (PDF) is a text file that contains definitions that map 3270 data stream commands to printer commands. A Host On-Demand PDF is not the same as an Adobe PDF file.
• A Printer Definition Table (PDT) is a binary file that you create by using the Printer Definition Table Compiler to compile the PDF file.

Broadly, the steps in compiling a PDF are as follows:

1. Start the Printer Definition Table Compiler.
2. Select a Printer Definition File (PDF).
   • Host On-Demand provides several predefined Printer Definition files.
   • You can create a custom Printer Definition File.
3. Click OK to compile the PDT.
4. The PDT Compiler compiles the PDF file, generates the PDT file, and places the PDT file in a directory on the server.

To deploy a PDT file to the workstation on which the Host On-Demand client is running:

• For the regular Host On-Demand client, you do not need to deploy the PDT file to the client workstation. The Host On-Demand client automatically downloads the PDT.
• For the locally installed client, you must copy the PDT to the workstation on which the locally installed client resides.

The following subsections describe how to create PDTs in more detail.

More about Printer Definition Files

A printer definition file (PDF) is an ASCII file that contains macro definitions, session parameters, formatting controls, and character definitions. You can edit a PDF with an ASCII text editor to customize it for your printer. Most printers support similar commands for basic functions, but they differ widely in their support for more advanced functions. Several PDFs are provided that should be suitable for most printers, except those that use PostScript and the HP Printing Performance Architecture (PPA).

You can compile and use PDFs from IBM Personal Communications for Host On-Demand. However, not all controls are supported.

Note that there is no connection between the PDFs in Host On-Demand and the Adobe PDF (Portable Document Format) files.

More about Printer Definition Tables

A printer definition table (PDT) is a file that is used to format the data stream that the host application sends. The Host On-Demand emulator converts the data stream from EBCDIC to ASCII (unless there is a passthru command in the data stream), formats the data according to controls specified in the data stream or in the PDT itself, and sends the data to the printer. You can use a simple PDT that contains basic instructions. However, if you want to use some of the newer workstation-printer functions, such as the ability to change fonts or paper-drawers, the PDT must be customized for your printer, and the host application must send the necessary commands. You must, in any case, use a PDT that is suitable for the emulation mode that the printer supports (HP PCL Level 3, IBM PPDS, and so on).

Several generic and specific PDTs are provided with Host On-Demand for both Single-byte Character Set (SBCS) and Double-byte Character Set (DBCS) printers. You can create customized versions of these or you can create entirely new ones. In either case, you need a Printer Definition File (PDF) from which to create a PDT.

Starting the Printer Definition Table Compiler

The compiler is a Java application that runs on a Host On-Demand server or a locally installed client. The compiler does not run on a download client.

When you start the compiler, it presents a graphical interface consisting of two entry fields: one for a PDT name and one for a printer description. A Status and Error Information window also appears. A log file called pdtc.log is created.

On a Windows NT, Windows 2000, or Windows XP server or a Windows client, you can start the compiler through Administration on the Start menu. On other platforms, you must start the compiler with a Java command. Sample command files are provided.

You can also start the compiler in non-graphical mode from a command line.

Locating Predefined Printer Definition Files and Tables

The PDFs and PDTs provided by IBM are installed in the pdfpdt subdirectory of the publish directory on a server (for example, C:\Program Files\IBM\HostOnDemand\HOD\pdfpdt) and in the equivalent subdirectory on a locally installed client ).

PDFs have the extension .pdf, and PDTs have the extension .hodpdt. A number of other PDFs are provided as examples and can be found in the samples\pdf directory of the publish directory (for example, C:\Program Files\IBM\HostOnDemand\HOD\samples\pdf).

For Arabic and Hebrew, prn*.pdf files are provided in the samples\pdf directory. To use one of these prn*.pdf files, copy the file from the samples\pdf directory to the pdfpdt\usrpdf directory, modify the copied file if necessary, and then compile it.

When compiling printer definition files shipped with Host On-Demand that contain Arabic or Hebrew markers, the resulting PDT does not appear in the Print Definition Table drop-down list in the printer properties on non-Hebrew or non-Arabic machines.  Refer to the Host On-Demand Hints and Tips website for detailed information.

Single-byte Character Set (SBCS) PDFs and PDTs

The following PDFs and PDTs are provided specifically for Host On-Demand:

PDFs contain annotations that explain the purpose of parameters. Each section begins with text that explains how the parameters can be used. For more information, refer to Understanding the Format of Printer Definition Files and Printer Definition File Example (3270).

Thai PDTs and PDFs

When the host code page is Thai (838 or 1160), the following PDFs and PDTs are available:

Thai

Double-byte Character Set (DBCS) PDFs and PDTs

For DBCS printers, the following PDTs and PDFs are provided:

Japan

Korean

China and Taiwan

The list of printer definition tables that appears on the Printer page of the session-configuration panel varies according to the Host Code Page that you set on the Connection page. In addition to those PDTs appropriate to the code page, the list includes any PDTs that you have created. If a session is configured for a DBCS code page, but you want to use an SBCS PDT, copy the appropriate PDF to the usrpdf directory and compile it with another name. It will then be a user-created PDT and will appear in the list on the configuration panel.

Supported Printer Emulation Modes

A PDT must be appropriate to the printer-emulation mode you want to use. For SBCS printers, the supported modes are:

• HP PCL Level 3
• IBM PPDS

For DBCS printers, the supported modes are:

• IBM PAGES
• IBM 5575
• ESC/P
• LIPS 3

If you are not sure which emulation modes or languages your printer supports, refer to the printer's technical documentation.

In some cases, it may be necessary to change the settings on the printer so that they match the mode for which the PDT is written. Some printers can switch between modes automatically or have software that enables you to change the mode. It is important to refer to the printer documentation to decide which PDT to use and how to set the correct mode on the printer. The printer manufacturer's Web site is another valuable source of information.

Most laser printers can use HP PCL level 3. Level-3 commands are understood by printers that support newer levels. All printers that provide the PPDS mode support PPDS level 1. Printers that support later levels of PPDS (3 or 4) will work with the LaserPPDS PDT. Proprinter-compatible printers and printers that support only PPDS level 1 cannot switch code-pages, so use the Proprinter PDT for these printers. Try basic ASCII text mode if your printer does not allow one of the other modes supported by Host On-Demand. However, if you use this mode, the commands that are unique to your printer will not be available. PDT mode does not support PostScript; however, the Native Printing mode does support PostScript though the appropriate PostScript printer driver.

Creating a Printer Definition Table (PDT) (3270)

If you are not able to use any of the IBM-provided PDTs, you can create one. However, you cannot create a PDT directly. You must first create a printer definition file (PDF), and then compile it to create a PDT.

Creating a Printer Definition File

You can create a new PDF either by typing it or by customizing one of the IBM-supplied PDFs. In either case, use an ASCII editor, because word-processing programs sometimes introduce spurious codes into the text.

Save the PDFs you create in the pdfpdt\usrpdf subdirectory of the publish directory of the Host On-Demand server (for example, C:\Program Files\IBM\HostOnDemand\HOD\pdfpdt\usrpdf) or in the equivalent directory on a locally installed client.

Before you attempt to create a PDF, you should understand its structure and the types of statements that can be included. See Understanding the Format of Printer Definition Files for help.

You should have the technical documentation for your printer available so you can look up the needed control codes. There are many variations from printer to printer.

If you want to customize one of the IBM-supplied PDFs to create your own, copy it from the pdfpdt directory to the pdfpdt\usrpdf subdirectory, modify it, and then compile it.

Using the Printer Definition Table Compiler

When you have created or modified a PDF, use the Printer Definition Table Compiler to create a PDT. You can run the compiler in graphical or nongraphical mode. PDTs that you create have names in the format usr*.hodpdt, where * is the name of the PDF that you compiled.

Printer Definition Table Description

Every PDT must have a unique description because this identifies the PDT when you configure a printer session. In graphical mode, the compiler checks that a unique description has been assigned. If it finds that a PDT with the same description already exists, it stops compiling and displays an error message. You can then  change the description and click OK to start again. In nongraphical mode, the compiler does not check that the description is unique.

Running the Compiler in Graphical Mode

The graphical mode lets you compile PDFs interactively. A log file called pdtc.log is saved in the pdfpdt\usrpdf directory.

Compiling a PDT on a Windows workstation or server

To compile a printer definition table on a Windows workstation or server:

1. Create a PDF and save it in the pdfpdt\usrpdf directory (for example, C:\Program Files\IBM\HostOnDemand\HOD\pdfpdt\usrpdf).
2. Click Start > Programs > IBM WebSphere Host On-Demand > Administration > Printer Definition Table Compiler.
3. Select the printer definition file from the pull-down list.
4. Type a description for the printer definition table that you are going to create. A description is essential because it serves to identify the PDT when you configure a printer session.

   If the description is not unique, an error message appears.

5. Click OK. The PDT is created in the pdfpdt directory. Status and error information appears at the bottom of the window and in the log file. If there are errors in the PDF, correct them and then recompile.

   If you want to compile other PDFs, repeat steps 3 - 5.

6. Click Exit when you have finished.

Compiling a PDT on an AIX, OS/2, or UNIX server

1. Copy the PdtCompilerApplication-AIX (or UNIX, or OS/2) file from the lib/samples/PdtCompiler directory in the Host On-Demand install directory (for example, from /opt/IBM/HostOnDemand/lib/samples/PdtCompiler) to a user directory (for example, /usr/local).
2. Modify the three variables in the PdtCompilerApplication-AIX file to match the installed system. Use the directions provided in the command file.
3. For UNIX servers only, change the file permissions for PdtCompilerApplication-UNIX to executable.
4. Run the PdtCompilerApplication-AIX (or UNIX, or OS2).
5. Select a PDF file from the pull-down and use it or modify it.
6. Enter a PDT description. This is name that Host On-Demand will use to identify this PDT.
7. Click OK.
8. Copy the PDF file to the pdfpdt/usrpdf directory. You may need to create the usrpdf directory.

Compiling a PDT on an iSeries server

To compile a printer definition table on an iSeries server, do the following:

1. Copy the PdtCompilerApplication-OS400 file from the lib/samples/PdtCompiler directory (for example, from /QIBM/ProdData/hostondemand/lib/samples/PdtCompiler) to your work directory
2. Edit the file to reflect your environment.
3. Run the qsh command to start a shell session.
4. Run the command file that you edited in step 2.

The compiler runs in nongraphical mode.

Compiling a PDT on a System/390

To compile a printer definition table on a System/390 server, do the following:

1. Save the PDFs created or modified in the pdfpdt/usrpdf subdirectory of the publish directory (for example, /usr/lpp/HOD/hostondemand/HOD/pdfpdt/usrpdf). Create the directory if it does not exist. 
2. Edit the PdtCompilerApplication-S390 found in /usr/lpp/HOD/hostondemand/HOD/samples/PdtCompilerCommandFiles. 

1. Verify the JAVA_ENGINE variable has the correct Java path.  
2. Modify the NONGUI_COMMAND line for the .pdf name and description. 

3. Run the PdtCompilerApplication-S390 command. 

The compiler runs in nongraphical mode.

Compiling a PDT on other platforms

On other platforms, including Novell Netware, you start the compiler with a command. To make this easier, sample command files are provided in the pdtcompilercommandfiles directory.

1. Copy the sample command file to a proper directory in your environment.
2. Edit the file to reflect your environment.
3. Run the command.
4. Select a printer definition file from the pull-down list.
5. Type a description for the printer definition table that you are going to create.
   

   If the description is not unique, an error message appears.

6. Click OK. The PDT is created in the pdfpdt directory. Status and error information appears at the bottom of the window and in the log file. If there are errors in the PDF, correct them and then recompile.

   If you want to compile other PDFs, repeat this process.

7. Click Exit.

Status and Error Information

The bottom window of the graphical interface displays status and error information. When you use the graphical interface, a history of each compiler run is saved in pdtc.log in the usrpdf subdirectory. The log is overwritten each time you start the compiler.

In addition to verifying that the PDT description is unique, the compiler checks that the syntax of the PDF is correct. Errors found are displayed in the Status and Error Information window and saved in the log.

Running the Compiler in Nongraphical Mode

This section does not apply to zOS.

If you want to compile several PDTs at one time, you can run the compiler in nongraphical batch mode by creating a command file and including multiple instances of the command that runs the compiler.

You can modify a version of the appropriate sample command-file provided in the pdtcompilercommandfiles directory; add any of the parameters listed below as necessary. If you compile several PDTs at one time, use the -NOINDEX parameter for each instance except the last, for which you should use the INDEX parameter. Create an index only after you have done the other compilations.

-NOINDEX

Causes the compiler to run in nongraphical mode and does not generate an index. This parameter is not recognized in graphical mode.

INDEX

Causes the compiler to run in nongraphical mode and to create an index, which lets Host On-Demand keep track of PDTs. When you use INDEX, you may not use any other options. Note that INDEX must not have a dash ( - ) before it.

-PATH pathSpecification

Causes the compiler to look for PDFs in the [pathSpecification]\pdfpdt directory.

-ENCOD encodingSpecification

Causes the PDF to be interpreted with the Java encoding-table specified rather than with the default table. You should use this if you are running the compiler on MVS and the MVS system uses an encoding-table different from that in which the PDF was created.

The command to invoke the compiler in nongraphical mode is:

   INSTALL_PATH/lib/samples/PdtCompiler/PdtCompilerApplication-XXX
   [-NOINDEX] | [-PATH pathSpecification] | [-ENCOD encodingSpecification] [PDF_file_name PrinterDescription]

If the PDF_file_name is present, the PrinterDescription must also be present. If the PDF_file_name is not present, the compiler runs in graphical mode.

After you have compiled your PDT(s), you must run the compiler again to create an index, which is essential. The command to invoke the compiler to create only an index is:

   INSTALL_PATH/lib/samples/PdtCompiler/PdtCompilerApplication-XXX INDEX

Compiled printer definition tables are saved in the pdfpdt directory (for example, in C:\Program Files\IBM\HostOnDemand\HOD\pdfpdt).

In nongraphical mode, compiler messages are displayed in English only.

Understanding the Format of Printer Definition Files (3270)

A PDF contains three main sections:

• Macro definitions
• Formatting controls
  • Session parameters
  • Control codes
• Character definitions

Macro Definitions

This section of a PDF contains macros that consist of a single mnemonic that represents a control code or a sequence of control codes. A mnemonic simplifies the definition of control sequences for PC printers and makes it easier to read the information in the PDF. The PDFs provided by IBM include many macros, but you can define also your own.

The following table shows the structure of a macro definition statement. A macro definition is composed of four parts:

For example:

   FFF    EQU   0C               /* Form Feed */

Part 1 is the mnemonic or macro name. This must be three characters long and must not begin with a number. It is helpful to define a meaningful mnemonic, such as P17 for 17.1 pitch.

Part 2, stands for "equates to" and must be coded as EQU.

Part 3, the hexadecimal control code, must be defined specifically for the printer you intend to use, because printer manufacturers use different codes for the same function. For example, the IBM LaserPrinter uses control codes defined by the IBM Personal Printer Data Stream (PPDS), whereas Hewlett-Packard printers use control codes defined by the Hewlett-Packard Printer Control Language (PCL). These control codes are defined in the reference manual for the printer (which you might need to order).

Some printer manuals describe control sequences as a string of ASCII symbols, such as ESC W 1. Others use hexadecimal numbers, such as 1B 57 01. Still others use decimal values, such as 027 087 001. The PDT compiler accepts any of these formats.

The control codes in the macro definitions section can be any of the following:

• Single characters that are interpreted as their ASCII values
• Two-digit numbers that are interpreted as hexadecimal values
• Three-digit numbers that are interpreted as decimal values

If the control code part of a macro (part 3) is blank, it is interpreted as a null string. If a code is defined more than once in the file, the last definition is used.

Part 4, the comment section, must be enclosed by /* and */. Comments can be included at any point in the file and are ignored by the compiler.

The following macro definition example is for a printer that supports IBM PPDS:

CRR EQU 0D             /* Carriage Return                             */
SEL EQU 11             /* Select Printer                              */
P10 EQU 12             /* 10 Pitch (characters/inch)                  */
P12 EQU 1B 3A          /* 12 Pitch (characters/inch)                  */
P05 EQU 1B 57 01       /* 5 Pitch (characters/inch), double wide      */
CDW EQU 1B 57 00       /* Cancel Double Wide                          */
CDL EQU 14             /* Cancel Double Wide line                     */
CS2 EQU 1B 36          /* Select character set 2                      */
SVT EQU 1B 42          /* Set vertical tabs                           */
CAT EQU 1B 52          /* Cancel all tabs (clears VT)                 */
SFL EQU 1B 43 00       /* Set Form Length                             */
SDS EQU 1B 47          /* Start Double Strike                         */
CDS EQU 1B 48          /* Cancel Double Strike                        */
SUL EQU 1B 2D 01       /* Start Underline                             */
CUL EQU 1B 2D 00       /* Cancel Underline                            */
CP8 EQU 1B 5B 54 04 00 00 00 03 52     /* select code page 850        */
CP4 EQU 1B 5B 54 04 00 00 00 01 B5     /* select code page 437        */
LL8 EQU 1B 41 09 1B 32 /* Set line length 8 lines/inch                */

Here is an example of how a macro might be used.

The host data stream contains a Word Underscore (WUS) command (LU1 SCS command 23). This indicates that the preceding word or string must be underlined. Host On-Demand converts the WUS command into START_HIGHLIGHT_UNDERLINE before the word and END_HIGHLIGHT_UNDERLINE after the word.

These controls are defined as macros SUL and CUL in the Control Codes section of the PDF:

     START_HIGHLIGHT_UNDERLINE=SUL
     END_HIGHLIGHT_UNDERLINE=CUL

When Host On-Demand receives the WUS command, it looks up the control codes and then looks up the macros. It finally sends the escape sequences defined in the macros to the printer. If the host sent a WUS command following the string "This is underscored", the following codes would be sent to the printer:

     54686973   20    6973   20    1B2D01   756E64657273636F726564   1B2D00

      T h i s  space   i s  space    SUL     u n d e r s c o r e d     CUL

The printed output is: "This is underscored"

Refer to Appendix A. Printer Data Stream Information for more information.

Formatting Controls

This section describes the session parameters, control codes, and highlighting specifications that can be included in a PDF.

Field Names and Parameter Definitions

The parameter to the left of the equal sign is a keyword and must be coded exactly as shown. The keyword defines a statement. The value to the right of the equal sign can be a word, a macro, a control code, a decimal number, or a hexadecimal number (sometimes referred to as a parameter).

Session Parameters

Session parameters determine the way in which the output is formatted. The session parameters in a PDF are related to the parameters in the Advanced Options panel of a session configuration, though there are many more options in a PDF than in the panel. If you do not change the defaults in the configuration panel, the values for the equivalent parameters in the PDT are used. Any change you make in the panel overrides the value in the PDT. Refer to Appendix C. Advanced Configuration Options for the list of session parameters that can be set in the panel.

The following table lists the field names and meanings of the Session Parameters.

Table 1. Session Parameters

ASCII_PASSTHRU? Keyword Support (LU1 Only)

If you add the following line to a PDF, Host On-Demand sends host data to the printer without translation:

     ASCII_PASSTHRU? = YES

This option is for host applications that generate PC printer control codes directly.

Even if ASCII_PASSTHRU? is set, control codes defined in the START_JOB and END_JOB sections of the PDF are sent to the printer at the start and end of a print job respectively. Remove them, if needed.   If ASCII_PASSTHRU? is set, all character definition lines, such as EBCDIC_xx, are ignored.   If both ASCII_PASSTHRU? and EBCDIC_PASSTHRU? are set, ASCII_PASSTHRU? takes precedence.

EBCDIC_PASSTHRU? Keyword Support (LU1 Only)

If you add the following line to a PDF, Host On-Demand ignores all SCS commands and sends only data to the printer after EBCDIC-to-ASCII translation:

     EBCDIC_PASSTHRU? = YES

If EBCDIC_PASSTHRU? is set, control codes defined in the START_JOB and END_JOB sections of the PDF are sent to the printer at the start and the end of a print job respectively. Remove them, if needed. If both ASCII_PASSTHRU? and EBCDIC_PASSTHRU? are set, ASCII_PASSTHRU? takes precedence.

The default EBCDIC-to-ASCII translation table used for U.S. English host code page 037 is as follows:

     Hex    0 1  2 3  4 5  6 7  8 9  A B  C D  E F
     ---------------------------------------------
       0 | 2020 2020 2020 2020 2020 2020 2020 2020
      10 | 2020 2020 2020 2020 2020 2020 2020 2020
      20 | 2020 2020 2020 2020 2020 2020 2020 2020
      30 | 2020 2020 2020 2020 2020 2020 2020 2020
      40 | 20FF 8384 85A0 C686 87A4 BD2E 3C28 2B7C
      50 | 2682 8889 8AA1 8C8B 8DE1 2124 2A29 3BAA
      60 | 2D2F B68E B7B5 C78F 80A5 DD2C 255F 3E3F
      70 | 9B90 D2D3 D4D6 D7D8 DE60 3A23 4027 3D22
      80 | 9D61 6263 6465 6667 6869 AEAF D0EC E7F1
      90 | F86A 6B6C 6D6E 6F70 7172 A6A7 91F7 92CF
      A0 | E67E 7374 7576 7778 797A ADA8 D1ED E8A9
      B0 | 5E9C BEFA B8F5 F4AC ABF3 5B5D EEF9 EF9E
      C0 | 7B41 4243 4445 4647 4849 F093 9495 A2E4
      D0 | 7D4A 4B4C 4D4E 4F50 5152 FB96 8197 A398
      E0 | 5CF6 5354 5556 5758 595A FDE2 99E3 E0E5
      F0 | 3031 3233 3435 3637 3839 FCEA 9AEB E9FF

You can modify this code page by using EBCDIC_xx keywords. Note that the EBCDIC_PASSTHRU? line must precede any EBCDIC_xx lines in a PDF because Host On-Demand re-initializes the EBCDIC-to-ASCII translation table when EBCDIC_PASSTHRU? is set.

Control Codes

The control codes section of a PDF defines which ASCII escape sequence is sent to the printer when a host control code is received. The escape sequence varies from printer to printer. The PDF must be written specifically for the emulation mode you use.

Control Codes used for both SBCS and DBCS Languages

The following table lists the field names and meanings of control codes that are used for both SBCS languages and DBCS languages.

Table 2. Control Codes

START_JOB and END_JOB

The control codes associated with START_JOB are sent at the start of each host print job. The control codes associated with END_JOB are sent at the end of each job.

Another application or a print job from another user might leave the printer in a mode that does not suit the job you want to print (for example, portrait orientation and Courier font). Set all printer options to a known or desired state at the beginning of each job using START_JOB. Similarly, because several users and applications share the printer, reset the printer to a known state at the end of each job using END_JOB.

For example:

     START_JOB=SEL CDW CDL CUL CDS CP8 CS2 SLO
     END_JOB=CAT CDW CDL CUL CDS CP4 SPO

In this example, the SLO macro is included in the START_JOB statement and the SPO macro is included in the END_JOB statement. The macros are coded as follows:

     SLO EQU 1B 6C     /* Set Landscape Orientation */
     SPO EQU 1B 6B     /* Set Portrait Orientation  */

The result is that the START_JOB statement sends a command to print the job in landscape orientation. The END_JOB statement sends a command to reset the printer to portrait orientation at the end of the job.

SET_VARIABLE_LINE_DENSITY

Use the SET_VARIABLE_LINE_DENSITY statement in combination with the lines-per-inch option in the Advanced Options panel of the session configuration.

The PDT substitutes the value set in the lines-per-inch field, divided into the LINE_SPACING_RATIO (72 for PPDS, 48 for PCL), for the value keyword in the SET_VARIABLE_LINE_DENSITY statement. The format of the PPDS command requires the result in binary form. The format of the PCL format requires the result in decimal (ASCII) form. For PPDS, the statement is:

     SET_VARIABLE_LINE_DENSITY=ESC A value ESC 2

     SET_VARIABLE_LINE_DENSITY=ESC A 09 ESC 2

     1B    41    09    1B    32
    (ESC    A    09    ESC    2)

CHARACTER_PITCH

On most printers, the default pitch is 10 characters per inch. This is usually coded in the PDF as:

SET_10_CHARACTERS_PER_INCH=P10

where P10 is coded in the macro definition section as:

P10 EQU 12     /* 12 is the printer control code for 10 pitch /*

REVERSE_VIDEO and BLINK

The reverse-video and blink codes do not have specified values because printers do not use them. You can use them to send any command you want to the printer by defining a macro, specifying the macro as the value for one of these codes, and sending the code (for example, START_HIGHLIGHT_BLINK) in the host data stream.

Using Custom Control Codes (LU1 and LU3)

Host On-Demand supports custom control codes in 3270 Printer LU1 sessions and in 3270 Printer LU3 sessions. (Host On-Demand does not support custom control codes for 5250 Printer sessions).

A custom control code is a pair of EBCDIC characters that Host On-Demand translates into a hexadecimal byte. Each member of the EBCDIC pair must be either in the range F0-F9 (representing '0'-'9'), or in the range C1-C6 (representing 'A'-'F'), or in the range 81-86 (representing 'a'-'f'). The first member of the pair represents the high nibble of the hexadecimal byte. The second member of the pair represents the low nibble of the hexadecimal byte. For example, the custom control code 81 f0 is translated into the hexadecimal byte a0.

Note: In fact, the translation is in two steps:

1. Host On-Demand converts an EBCDIC pair to an ASCII pair. For example, EBCDIC 81 f0 is converted to ASCII 61 30.
2. Host On-Demand translates the ASCII pair to a hexadecimal byte. For example, ASCII 61 30 is translated to hexadecimal a0.

• EBCDIC F0-F9 converts to ASCII 30-39.
• EBCDIC 81-86 converts to ASCII 61-66.
• EBCDIC C1-C6 converts to ASCII 41-46.

In the LU1 or LU3 print data stream, custom control codes must occur inside a custom control code block (which is discussed later in this section). Any number of custom control code blocks can occur in a print data stream. Each custom control code block can contain one or more custom control codes (that is, one or more pairs of EBCDIC characters).

Notice the following:

• The data inside a custom control code block must consist of an even number of EBCDIC characters, because each custom control code consists of two EBCDIC characters. If Host On-Demand finds that the last pair of a custom control code block is broken (contains only one EBCDIC character), then Host On-Demand skips that custom control code.
• Each member of a custom control code must translate to a valid hexadecimal numeral. For example, the custom control code f1 e8 is invalid, because e8 does not translate to a valid hexadecimal numeral. In this situation, Host On-Demand sends both characters in the pair to the printer, unconverted (f1 e8).

Control codes

The control codes used to manage custom control codes are:

• CUSTOM_CONTROL_CODES?
• CUSTOM_CONTROL_CODES_HEADER
• CUSTOM_CONTROL_CODES_LENGTH
• CUSTOM_CONTROL_CODES_TRAILER

The control code CUSTOM_CONTROL_CODES? is used to enable or disable custom control codes:

• If this control code is not present in your PDF file, then custom control codes are disabled. (The PDF files provided with Host On-Demand do not contain this control code.)
• If you add this control code to your PDF file and set it to YES, then custom control codes are enabled:

  CUSTOM_CONTROL_CODES?=YES

• If you include this control code in your PDF file and set it to NO, then custom control codes are disabled:
  

  CUSTOM_CONTROL_CODES?=NO

The control code CUSTOM_CONTROL_CODES_HEADER, when it appears in the LU1 or LU3 print data stream, signals the beginning of a custom control code block. You must define this control code in the control codes section of your PDF file, setting it to some macro value or to some series of literal values. For example,

CUSTOM_CONTROL_CODES_HEADER=6c 6c

The control code CUSTOM_CONTROL_CODES_TRAILER is used only in header-trailer mode (see below). This control code, when it appears in the LU1 or LU3 print data stream after a CUSTOM_CONTROL_CODES_HEADER, signals the end of a custom control code block. You must define this control code in the control codes section of your PDF file, setting it to some macro value or to some series of literal values. For example,

CUSTOM_CONTROL_CODES_TRAILER=6c 6c

The control code CUSTOM_CONTROL_CODES_LENGTH is used only in header-length mode (see below). This control code does not appear in the LU1 or LU3 print data stream. Instead, it defines the fixed number of custom control codes (EBCDIC pairs) that occur in every custom control code block in the print data stream. You must define this control code in the control codes section of your PDF file, setting it to some macro value or to some series of literal values. For example:

CUSTOM_CONTROL_CODES_LENGTH=1

Modes

Within a single LU1 or LU3 print data stream, you can use custom control codes either in header-trailer mode or in header-length mode. You cannot use both modes in the same print data stream.

Header-trailer mode

In header-trailer mode, a custom control code block consists of:

• A CUSTOM_CONTROL_CODES_HEADER; followed by
• 0 or more custom control codes (EBCDIC pairs); followed by
• A CUSTOM_CONTROL_CODES_TRAILER.

You must have Host On-Demand use header-trailer mode when the print data stream contains custom control code blocks of different lengths. For example, you must have Host On-Demand use header-trailer mode if the print data stream contains some custom control code blocks containing one control code (1 EBCDIC pair) and other custom control code blocks containing two control codes (2 EBCDIC pairs).

To indicate that you want Host On-Demand to use header-trailer mode, define the CUSTOM_CONTROL_CODES_TRAILER in the control codes section of your PDF file. Here is an example of how to define the relevant control codes in your PDF file when you want to use header-trailer mode:

CUSTOM_CONTROL_CODES?=YES
CUSTOM_CONTROL_CODES_HEADER=6c 6c
CUSTOM_CONTROL_CODES_TRAILER=6c 6c

Here is an example of a custom control code block that Host On-Demand could process using the above definitions.

6c 6c f1 82 f1 83 6c 6c

1. When it encounters the header 6c 6c, Host On-Demand recognizes that it must process subsequent pairs as custom control codes.
2. Host On-Demand converts EBCDIC f1 82 to hexadecimal 1b, and then sends this hexadecimal 1b to the print destination.
3. Host On-Demand converts EBCDIC f1 83 to hexadecimal 1c, and then sends this hexadecimal 1c to the print destination.
4. When it encounters the trailer 6c 6c, Host On-Demand recognizes that it has reached the end of the custom control code block.

Additional rules for header-trailer mode:

• For LU1 sessions, a custom control code block may span several RUs. If a custom control code block spans several RUs but does not include a final CUSTOM_CONTROL_CODES_TRAILER, Host On-Demand does not treat this as an error. Instead, Host On-Demand assumes that the custom control code block ends when the last-in-chain RU ends.
• For LU3 sessions, if Host On-Demand finds a CUSTOM_CONTROL_CODES_HEADER but then reaches the end of the presentation space without finding a CUSTOM_CONTROL_CODES_TRAILER, Host On-Demand does not treat this as an error. Instead, Host On-Demand assumes that the custom control code block ends at the end of the presentation space.
• An empty custom control code block, consisting of a header immediately followed by a trailer, is valid.
• A string of characters that occurs within a custom control block (after a header and before a trailer), and that is identical with the header, and that is not identical with the trailer, is treated as a custom control code. For example, if you have defined the header to be 6c 6c and the trailer to be 5f 5f, then Host On-Demand processes the sequence

  6c 6c 6c 6c 5f 5f

  as a header (6c 6c), followed by a custom control code (6c 6c), followed by a trailer (5f 5f).

Header-length mode

In header-length mode, a custom control code block consists of:

• A CUSTOM_CONTROL_CODES_HEADER; followed by
• A fixed number of custom control codes (EBCDIC pairs).

You can have Host On-Demand use header-length mode only when the print data stream contains custom control code blocks all of the same length. For example, you can have Host On-Demand use header-length mode if the print data stream includes only custom control code blocks that contain two control codes (2 EBCDIC pairs).

To indicate that you want Host On-Demand to use header-length mode, define the CUSTOM_CONTROL_CODES_LENGTH in the control codes section of your PDF file. Here is an example of how to define the relevant control codes in your PDF file when you want to use header-length mode:

CUSTOM_CONTROL_CODES?=YES
CUSTOM_CONTROL_CODES_HEADER=5f 5f
CUSTOM_CONTROL_CODES_LENGTH=2

• Do not define the CUSTOM_CONTROL_CODES_TRAILER control code. When you include this control code, Host On-Demand assumes that you want to use header-trailer mode, even if you have also defined CUSTOM_CONTROL_CODES_LENGTH.
• If you do not define the CUSTOM_CONTROL_CODES_LENGTH, then Host On-Demand assumes a length of 1 (1 EBCDIC pair).

Here is an example of a custom control code block that Host On-Demand could process using the above definitions.

5f 5f f1 82 f1 84

1. When it encounters the header 5f 5f, Host On-Demand recognizes that it must process subsequent pairs as custom control codes.
2. Host On-Demand converts EBCDIC f1 82 to hexadecimal 1b, and then sends this hexadecimal 1b to the print destination.
3. Host On-Demand converts EBCDIC f1 84 to hexadecimal 1d, and then sends this hexadecimal 1d to the print destination.
4. Having processed two control codes (two EBCDIC pairs), Host On-Demand recognizes that it has reached the end of the custom control code block.

Additional rules for header-length mode:

• A custom control code block may span several RUs. However, if a custom control code block spans several RUs and the last-in-chain RU does not contain enough bytes to make up the expected length, Host On-Demand treats this as an error.

Additional Control Codes for DBCS

The following table lists the field names and meanings of the DBCS-specific Control Codes. Refer to Code Pages Supported in Host On-Demand for the complete list of code pages.

Table 3. Additional Control Codes for DBCS