VERIFIED SOLUTION i
X

Troubleshooting EPS Backgrounds in Vault

Issue

My emulated paper stock is not displaying properly in Vault.  I am getting an error message when trying to view a document that is using emulated paper stock.

Cause

By default, Vault embeds the content of the background into the beginning of the page without modification. This can be the source of many types of problems as the contents of the background could easily conflict with the content of the page itself.

Resolution

UPDATED: September 26, 2017


Troubleshooting EPS Backgrounds

Background on Backgrounds

Vault supports rendering Postscript documents with backgrounds that simulate preprinted paper stock.

Background Types

There are two background type that are supported. GIF backgrounds and Encapsulated PostScript (EPS) backgrounds. EPS backgrounds are used in bitmap, PDF and printing. GIF backgrounds are only used when rendering to GIF. They’re supported for backwards compatibility and should not be used for new data if possible. Note that PDF backgrounds using TrayMode are not supported with Postscript.
EPS backgrounds are saved to the resource set with the .ps extension rather than an .eps extension as would be typical. The files should not have a binary header. Unlike GIF backgrounds, you only need a single EPS file for a given paper stock.

Background Injection

By default, Vault embeds the content of the background into the beginning of the page without modification. This can be the source of many types of problems as the contents of the background could easily conflict with the content of the page itself.
For newer versions of Vault, you can set the profile setting PSBackgroundMode=2. This causes Vault to reference the background as an external file rather than inject it into the page. This mode also wraps the background in a save/restore pair to help avoid the background from altering the state of the interpreter that the page may depend on. It also undefines the showpage operator so that the background does not cause an extra page break to be generated between the background and page content. This setting was introduced as a patch 6.1M0p0087. It appears in the release version of 7.0 and later.
For older versions of Vault this option is not available. But it can be simulated to some extent by editing the background file. Add the following commands before and after the normal content of EPS background:
resourceset\background.ps:
save /showpage {} bind def
 
%!PS-Adobe-3.0 EPSF-3.0
<remaining content of the EPS background>
%%EOF
 
restore

Background Selection

Many customers have documents that need different paper stocks depending on the page being rendered. The way background selection works in Postscript is slightly different from other modes.
ScenarioProfileResulting Background
fixed backgroundduplex=0
tray=basename
all pages: basename.ps
different front/back backgroundsduplex=1
tray=basename
odd pages: basename.ps
even pages: basename-back.ps
different background for first pageduplex=2
tray=basename
first page: basename.ps
remaining pages: basename-body.ps
automatic detection(duplex not set)
tray=basename
with “/MediaType (alpha)”: alpha.ps
with “%%PageMedia: beta”: beta.ps
otherwise: basename.ps
 
For simple cases, use the fixed duplex modes. More complicated situations rely on commands in the Postscript page to determine the background to use.
Postscript backgrounds do not support TrayMode stock selection.

Updating the Ghostscript Library

Updating the Ghostscript library can help resolve certain types of rendering errors. To do that, you need to replace the gsdll32.dll file in the render and client directories with one from a newer version of Vault. You must also replace the content of the lib directory tree at the same time as it is matched to the .dll. In some cases you’ll also need to copy or install C++ runtime libraries (either e2renderd or e2ps won’t start).
Do not use GPL Ghostscript versions with Vault. We don’t ship them or support them. I would also be careful about installing another instance of Ghostscript on the same machine. This sometimes sets registry settings that affect Vault’s Ghostscript instance. For example you might see it attempt to scan another directory for fonts:
Scanning c:\psfonts for fonts... 0 files, 0 scanned, 0 new fonts.

Common Symptoms

Foreground Text Appears with the Wrong Orientation

If the background is displayed but the foreground text is incorrectly oriented, it may be that the background being injected into the page is affecting the current text state. Text orientation during Postscript execution is controlled in part by the current transformation matrix. If an injected background alters this matrix without restoring it to its initial state, the foreground text may be displayed incorrectly.
To fix this, use the PSBackgroundMode=2 profile setting if available or alter the background to save and restore the transformation state. See “Background Injection” above for more details.

Background Appears as a Separate Page in PDF Export

If a background is appearing as a separate page before the page it applies to, the background may be issuing a showpage command. The showpage command will cause a page break to be generated when rendering to PDF.
To fix this, use the PSBackgroundMode=2 profile setting if available or alter the background to disable the showpage command (either by redefining it or commenting it out). See “Background Injection” above for more details.

Background Does Not Appear

There are a number of reasons why a background might not take effect. Make sure you examine the profile settings to ensure you have the right background file name. You may need to examine the page content for MediaType and PageMedia commands. Check the resource set at the rendering engine to see that the background file is present and accessible. Make sure the EPS background has the .ps file extension Vault expects rather than the normal .eps extension.
In particularly old versions of Vault the Postscript backgrounds files are not automatically downloaded to the rendering engine from the server.
Note that some versions of Service Web 2 do not display backgrounds by default.

Wrong Background Appears

Make sure you examine the profile settings to ensure you have the right background file name. Note that in some cases when using automatic background selection multiple MediaType or PageMedia directives may appear on the page. Vault looks for MediaType before PageMedia. If multiple directives of the same type are present, it takes the first one. If you need the later directive, you might be able to disable the earlier one with carefully chosen search and replace profile settings (PS_Search1/ PS_Replace1) but ultimately it is difficult to automatically select backgrounds for such streams.
Some customers try to configure TrayMode type backgrounds with Postscript and run into trouble with the wrong backgrounds. This is because Postscript rendering in Vault does not support TrayMode or its PDF based backgrounds.

Undefined File Name When Background is Configured

If you configure Postscript backgrounds and a message appears in the rendering log such as this:
Error: /undefinedfilename in (basename.ps)
You probably have configured PSBackgroundMode=2, referencing the external background file, but the file does not exist. Check the resource set at the rendering engine to verify the requested background file is present and accessible.
Note that you sometimes get this sort of error when using FileMode=1 because it is trying to load the resource.ps file. In some cases this file can be created in the resource set with blank lines. This case is not directly related to backgrounds however and happens whether or not backgrounds are configured.

Other Errors When Background is Configured

In some cases when a background is embedded using the default method, it alters the state of the running interpreter and causes the execution of the page content to fail with an error. These errors are often quite random. They could be related to undefining/redefining operators that the page uses or changes to the dictionary stack state. But, the symptoms go away if no background is used.
For example:
Error: /undefined in -run-
Again, this is a case where you should use the PSBackgroundMode=2 profile setting if available or alter the background to save and restore the transformation state. See “Background Injection” above for more details.
In other cases this can be cause by having a binary wrapper around the EPS file. Use a text editor to see if there is binary data before the line:
%!PS-Adobe-3.0 EPSF-3.0
Errors could also result if the EPS file is incorrect or damaged in other ways. You can use Ghostscript to render the background in isolation.
gcwin32c resourceset\background.ps
This might not display with the correct page dimensions but it shouldn’t produce errors on the console.
You might also run into errors if the background is not an EPS file but a Postscript file. You can use Ghostscript to convert the background from Postscript or PDF to EPS, for example:
gswin32.exe -dBATCH -dNOPAUSE -sDEVICE=epswrite -dLanguageLevel=2 -sPAPERSIZE=a4 -dEPSCrop -sOutputFile=e:\temp\output.ps e:\temp\input.ps

Bounding Box Warnings When Rendering Backgrounds

In some cases, when rendering backgrounds you’ll get a warning from Ghostscript indicating a problem with the bounding box:
**** Warning: Some of the BoundingBox for the EPS file will be clipped.
Use -dEPSCrop or -dEPSFitPage to avoid clipping.
Generally this indicates a mismatch between the page dimensions and the background being used. Check that the background EPS file uses the same dimensions as the page. Check that the bounding box is being set to the whole page and not just the content (how this is set varies on the tool used to create the EPS file).
If all else fails, you can use the suggested settings in the profile by using the OptionN= settings that pass one or more Ghostscript switches to the interpreter:
profiles.ini:
[someprofile]

Option1=-dEPSFitPage
 

Settings

[profile]PSBackgroundModeThis option controls how EPS backgrounds are inserted into the page for rendering.
 
Set to 1 to embed the contents of the EPS background into the start of the page as-is. This is the default behavior.
 
Set to 2 to insert a reference to the external background file. The reference is wrapped in save/restore operators in order to prevent the EPS file from affecting the execution of the rest of the page. This option also redefines the showpage operator so that if the EPS file uses it, an extra page won't be generated unintentionally.
 RedirectFontPathThis controls whether the resource set is scanned for fonts during Postscript rendering.
 
Set to 1 (the default), the resource set directory is added to the font resource path scanned by Ghostscript.
 
Set to 0, the resource set directory is not added to the font search path.
 
In some cases, the font scanning process will produce errors that cause rendering operations to fail. In this case, set this option to 0.
 OptionX=Option1= to Option9= are settings that are passed to the underlying Ghostscript instance during Postscript rendering.
 
For example:
Option1=-sPAPERSIZE=a4
Option2=-dAutoRotatePages=/None
Option3=-dEPSFitPage
 
How to use Ghostscript
http://www.ghostscript.com/doc/9.07/Use.htm
 PS_Search1 =
PS_Replace1=
PS_Flags1=
In certain situations, data loaded into the Vault must be modified before being used. The search and replace function allows you to change data appearing in the output data stream.
 
The syntax of the search/replace is shown below:
PS_Search<n>=text to search for
PS_Replace<n>=text to replace with
PS_Flags<n>=replacement options
 
You may specify multiple search-and-replace entries, each with a different number. The numbers must start at one and be contiguous.
 
Sometimes used to comment out setpagedevice or other operators.
 

Tools

gswin32c.exeAn executable from Ghostscript proper that gives you access to the interpreter from the command line. Can be used to render or convert backgrounds.
 

Documentation

Vault Customizing Guide
  • Emulating paper stock
  • PSBackgroundMode
  • Emulating paper stock
  • Postscript Backgrounds
  • EPS export for postscript files (out of date?)
 

Patches

5.5M0p0300Fixed an issue where the Postscript header was being transferred incorrectly leading to random Ghostscript render errors.
6.1M0p0087This build adds a profile option to control how EPS backgrounds are inserted into the page for rendering.
 
PSBackgroundMode=1 (default)
Embed the contents of the background into the start of the page as-is.
This is the existing behavior.
 
PSBackgroundMode=2
Insert a run command of the external background wrapped in a save/restore.
It also redefines showpage so that an extra page does not get created by some EPS files.
 
With this patch and the PSBackgroundMode=2 profile setting in [GlobalstarUSA], you do not have to alter the background file as mentioned above.
7.0M2p0033The Postscript compressor now moves in page resource data between %ADOBeginSubsetFont and %ADOEndSubsetFont markers to the secondary header. Previously, rendering errors could result when subsetted fonts were declared using these markers as the resource data was not available to all pages using the font.
 
Notes:
- jobs compressed by previous versions will continue to behave as they currently do since the resource data would still be located in specific pages
- in general (or as a workaround), disable font subsetting in Postscript files being sent to Vault

 

Downloads

  • No Downloads