Solved Creating a working PCL overlay from print to file


Well-Known Member

Reaction score: 24
Messages: 420

I am working on converting some print forms to run through FreeBSD and ghostscript. I am trying to discover exactly what changes must be made to the form and data print files so that they will merge on a PCL5 printer.

The form overlay is created from LibreOffice draw and is printed to a file using a virtual printer created in CUPS using the hpcups_3 driver. The data file is created on another host running a legacy OS and is a simple ASCII text file with a PCL prefix string specifying the font to use. That font is the line-printer font built in to the printers that we use.

I have discovered the <esc> sequences that I must use to create and save a PCL macro. And I have the PCL escape sequences for calling a previously loaded PCL overlay. What I cannot seem to determine is where these sequences are supposed to be placed in the overlay PCL file and the data file.

The beginning of the overlay file initially printed from DRAW contains this:
<esc>&l7h0m2a0s8c0o0E<esc>*o . . . <null><null>ú<null><ff><esc>*rC<esc>E<esc>%-12345X

I understand that the <esc>%-12345X string resets the printer and places it in PJL mode. So that is the delimiter for the beginning and end of a PCL print job. In the overlay the PCL job commands are pointless, so those can be removed. The <Esc> sequence after the PCL commands is the actual form I believe. The final <esc>%-12345X resets the printer for the next job.

The strings to create and load a form overlay macro from PCL source are:
<esc>&f0X                               # start of macro definition

<pcl code here>                         # macro definition

<esc>&f22y1X                            # end of macro definition id=22
<esc>&f22y10X                           # make macro permanent until printer reset

How are these strings used in the overlay file?

Is it:
a. <esc>&f0X <esc>%-12345X . . . <esc>%-12345X <esc>&f22y1X <esc>&f22y10X;
b. <esc>%-12345X <esc>&f0X . . . <esc>&f22y1X <esc>&f22y1X <esc>%-12345X;
c. <esc>&f0X . . . <esc>&f22y1X <esc>&f22y1X; or
d. something else ?

Do the strings <esc>&f0X and <esc>&f22y1X replace <esc>%-12345X at the beginning and end of the overlay PCL code? Or do they used inside, or outside, thePCL job delimiter strings? Or is there some other arrangement that is used?

Given the the macro is successfully loaded, where in the data file does the <esc>&f22y4X go to trigger the use of the overlay?
Note that both sets of commands are using index 22 to identify the form overlay macro to the printer. The macro index is an arbitrary value.
Last edited:


Well-Known Member

Reaction score: 24
Messages: 420

I discovered that one cannot really edit PCL files with gvim. In the end I used an automated utility to turn PCL files into PCL overlay macros. The steps are given below.

1. Have cupsinstalled.
2. Enable the FileDevice in cups: /usr/local/etc/cups/cups-files.conf:FileDevice Yes.
3. Define a printer in CUPS using AppSocket/HP JetDirect with a connection similar to file:/var/spool/pcl_out/fixed_file_name.pcl using the basic HP LaserJet 3 - CUPS+Gutenprint v5.3.3 (grayscale) driver. Give the printer a suitable name.
4. Produce an overlay document in any application that can print to the printer created above. I used LibreOffice Draw.
5. Print the overlay from the source application to the printer name chosen for the PCL printer.
6. Obtain pcloverlay source from
Modify the Makefile to specify CC=gcc and remove the -befl setting in CFLAGS=.
7. Run gmake and create the binary executable. (make and clang may work, I did not try these)
8. Using the PCL printer file created above as the source run pcloverlay -d </var/spool/pcl_out/fixed_file_name.pcl >myoverlay.ovl
9. At this point one has several paths that one can follow to arrive at much the same end. I am showing only one. Concatenate the printer text file and the overlay created above: cat myoverlay.ovl mybasefile.txt > my_base_with_overlay.prn
10. Print the merged file using: lpr -l -P printer my_base_with_overlay.prn

Providing that the printer chosen supports PCL3 one will now have a merged printed document. Some points to consider:

1. The overlay source must be in PCL3 to be transformed by pcloverlay. Any PCL source above level 3 will result in scrambled output.
2. The base document PCL must not contain PCL commands specifying the paper size or orientation ( <ec>&f#O) or contain a printer reset ( <ec>E). The presence of either of these, and possibly many more I did not encounter, will diable the overlay macro.
3. pcloverlay uses form index id 1. If one prints to a printer that has another overlay already loaded as index 1 it will be replaced.
4. lpr -l -(ell) sends the raw PCL stream directly to the printer. This is a requirement.
5. The CUPS file printer file name is fixed. A subsequent print job will overwrite the previous.

One can produce a pdf document from my_base_with_overlay.prn using the gpcl6 program. Like pcloverlay this has to be built from source on FreeBSD because it is not included in the ghostcript port. The syntax is similar to:

gpcl6 -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=/tmp/\"$(date -Iseconds)\".pdf my_base_with_overlay.prn