Installing and Using Adobe Acrobat Viewer (for Java) on OpenVMS Alpha Systems

Overview

Now you can view Adobe Portable Document Format (PDF) files on Compaq® OpenVMSTM Alpha systems.  Adobe PDF is a universal file format that preserves all the fonts, formatting, colors, and graphics of any source document, regardless of the application and platform used to create it.

Adobe Acrobat Viewer allows you to view PDF files on OpenVMS Alpha systems that have the Java Virtual Machine (JVM) installed.  Adobe provides the Viewer free of charge from its web site.

This document contains the following topics:

Prerequisites
OpenVMS Tasks
Downloading the Viewer
Installing the Viewer
Using the Viewer
Printing
Tuning
Troubleshooting

Prerequisites

To install and run the Adobe Acrobat Viewer, you need the following software:

OpenVMS Tasks

You must perform the following tasks on your OpenVMS Alpha system before installing the Acrobat Viewer.  Enter the commands exactly as they are shown.
  1. Set the following quotas using the AUTHORIZE utility:

  2.             Pagefile quota - suggested minimum 128000
                Working set quota - suggested minimum 64000
                Working set extent - suggested minimum 128000
     
  3. Install Java (if not already installed) and startup Java:

  4.  
    $ @SYS$STARTUP:JAVA$STARTUP.COM
  5. Add the SYS$STARTUP:JAVA$STARTUP.COM file to the system startup procedure, so that Java will be started each time the system starts.
  6. Invoke the setup file for any account that will install or run the Viewer:

  7.  
    @SYS$MANAGER:JAVA$SETUP.COM
  8. Check whether the correct version of Java (V1.1.8 or higher) is installed and running  and that the setup command procedure was issued correctly.   The following command should return a string containing 1.1.8 or higher:

  9.  
    $ java -version
    Note:  Java commands are case sensitive; they must be entered exactly as shown and  be enclosed in quotation marks.
     
  10. Define the CLASSPATH to have only the JDK V1.1.8 or higher file and the VIEWER.ZIP file in it.  The following example places the file in SYS$SYSDEVICE:[ACROBATVIEWER] directory; however, you can place viewer.zip elsewhere on your system.

  11. $ DEFINE CLASSPATH -
    "/sys$common/java/lib/jdk118_classes.zip:.:/sys$sysdevice/acrobatviewer/viewer.zip"
Note:  This command syntax does not use the normal OpenVMS file specification syntax.   The OpenVMS specification SYS$COMMON:[JAVA.LIB]JDK118_CLASSES.ZIP changes to /sys$common/java/lib/jdk118_classes.zip, including the leading slash.  If any other .ZIP or .JAR files are included, the installation procedure may fail.

Downloading the Viewer

Download the Adobe Acrobat Viewer in zip (binary) format from the Adobe Acrobat web site.  Or, you can copy the Viewer from the .EXE folder on the Documentation CD-ROM.  After downloading the zip file or copying it from the CD-ROM,  check to see whether the record format is Stream_LF.  A full directory of the file should look like this:

VIEWER.ZIP;1                  File ID:  (12836,1,0)
Size:         5371/5376       Owner:    [SYSTEM]
Created:   13-APR-2000 07:14:55.00
Revised:   17-APR-2000 10:57:06.00 (13)
Expires:   <None specified>
Backup:    <No backup recorded>
Effective: <None specified>
Recording: <None specified>
File organization:  Sequential
Shelved state:      Online
Caching attribute:  Writethrough
File attributes:    Allocation: 5376, Extend: 0, Global buffer count: 0, No version limit
Record format:   Stream_LF, maximum 32767 bytes, longest 32767 bytes
Record attributes:  Carriage return carriage control
RMS attributes:     None
Journaling enabled: None
File protection:    System:RWED, Owner:RWED, Group:RE, World:
Access Cntrl List:  None
Client attributes:  None

Total of 1 file, 5371/5376 blocks.

The Record format information is important.  If it is not Stream_LF,  issue the following command to set the proper file attributes:

$ SET FILE/ATTRIBUTES=RFM:STMLF VIEWER.ZIP

Installing the Viewer

Before starting the installation procedure:
1.  Create the directory where you are going to install the Viewer.    For example:
    $ CREATE/DIRECTORY SYS$SYSDEVICE:[ADOBEACROBATVIEWER]
2.  Set the protection on this directory to give execute access to all users who will run the Viewer.  For example:
    $ SET PROTECTION=WO:E SYS$SYSDEVICE:[0,0]ADOBEACROBATVIEWER.DIR

Once the setup is complete, issue the following command to start the installation procedure:

$ java "install"

Note:  Java commands are case sensitive; they must be entered exactly as shown and be enclosed in quotation marks.

The installation procedure displays several pop-up windows showing the progress of the installation.  These windows allow you to select the location where you want the files installed.  When the installation procedure completes, a dialog box is displayed stating that the installation is complete and that the Viewer will start.  However, on OpenVMS, the Viewer will not start automatically.  You must first perform the following actions after the installation is complete:

After the installation is complete:

  1. Check that the file ACROBAT.JAR was created and placed in the directory where the Viewer is installed.
  2. Set the protection on this file to world read and world execute to give users who will run the Viewer access to the file.  For example:
    $ SET PROTECTION=WO:RE SYS$SYSDEVICE:[ADOBEACROBATVIEWER]ACROBAT.JAR

Using the Viewer

Before using the Viewer, set the CLASSPATH to point to the proper files. For example:

$ DEFINE CLASSPATH -
"/sys$common/java/lib/jdk118_classes.zip:.:/sys$sysdevice/adobeacrobatviewer/acrobat.jar"

SYS$SYSDEVICE:[ADOBEACROBATVIEWER]ACROBAT.JAR is the path in which the Viewer was installed. Users must define their own path.

Note: If you run other Java-based applications, you must change this logical name by restoring the definition to the value given before you ran the Viewer. Placing additional .ZIP or .JAR files in the definition of CLASSPATH may cause problems with the Viewer.

Starting the Viewer
To start the Viewer, issue the following command:

$ java -mx32m "com.adobe.acrobat.Viewer" PDF-file

You can start the Viewer without specifying a PDF file; the Viewer prompts you for the name of the file to be read.  You can change your preferences to suppress the initial file prompt.

Note: The portion of this command line within quotation marks is case sensitive; you must enter it exactly as shown, including the quotation marks.

When using the Viewer, notice that the Close item on the File menu not only closes the document, but also exits the program.  If you want to view another document without exiting the Viewer, simply open the new document.  This action closes the first document and opens the new one.

When you run the Viewer, it creates an ACROBAT.PROPERTIES file, which is placed in your login directory by default.  The ACROBAT.PROPERTIES file contains your preference settings and should also be in Stream_LF format.

In addition to the properties file, the Viewer creates an [.ACROBATFONTS] directory below your default login directory and places a FONTCACHE.SER file in  that directory.  The Viewer creates new versions of the ACROBAT.PROPERTIES and FONTCACHE.SER files each time you run it.  You may want to purge the old files occasionally.

Note:  If you are running in an account such as SYSTEM, which is on a multiply rooted disk, the Viewer may not be able to create the [.ACROBATFONTS] directory, and therefore will not be able to save
the FONTCACHE.SER and ACROBAT.PROPERTIES files.  You can correct this by creating the directories manually.  For example:

$ CREATE/DIRECTORY SYS$SYSROOT:[SYSMGR.ACROBATFONTS]
$ CREATE/DIRECTORY SYS$COMMON:[SYSMGR.ACROBATFONTS]

If your disk has more than one root,  create the SYS$SYSROOT:[SYSMGR.ACROBATFONTS] for each root.

Invoking the Viewer from Mozilla and Navigator

This section shows how to set up the Acrobat Viewer as a helper application in Mozilla for OpenVMS and Netscape Navigator for OpenVMS. After completing these steps, when the Mozilla or Navigator browsers encounter a PDF file, they automatically invoke the Acrobat Viewer to display the contents of the PDF file.

To set up the Adobe Acrobat Viewer as a helper application, perform the following steps:

  1. Install Mozilla for OpenVMS Alpha or Netscape Navigator for OpenVMS Alpha.
  2. Create the following file, PDF.COM, in the directory where you have installed the Adobe Acrobat Viewer (the file acrobat.jar should already be in this directory):
  3. $ sv = f$verify(0) 
    $ adobe_jar_file = "/dka0/adobeacrobatviewer/acrobat.jar" 
    $ @sys$manager:java$setup 
    $ cp = f$trnlnm("classpath") + ":" + adobe_jar_file 
    $ define /user classpath "''cp'" 
    $ sv = f$verify(sv) 
    $ java -mx32m "com.adobe.acrobat.Viewer" 'p1' 
    $ exit
  4. Modify the second line of PDF.COM for your system. The value of adobe_jar_file must be the UNIX-style full file specification of the ACROBAT.JAR file. This example uses /dka0/adobeacrobatviewer/acrobat.jar, which is the UNIX-style format of DKA0:[ADOBEACROBATVIEWER].
  5. Make sure that the file protection of PDF.COM allows users access to it. For example:
  6. $ SET FILE /PROTECTION=WORLD:READ DKA0:[ADOBEACROBATVIEWER]PDF.COM
  7. The command file PDF.COM can now be used to view any PDF file. Test that you have PDF.COM set up correctly before you configure Mozilla.
  8. $ SET DEFAULT DKA0:[ADOBEACROBATVIEWER] 
    $ @PDF HELP.PDF
  9. If you have installed Mozilla, configure Mozilla (M18 or later) for the helper application by following these steps:
    1. Start Mozilla
    2. From the menu bar, select "Edit" and then "Preferences..."
    3. From the Navigator section, select "Helper Applications"
    4. In the "Helper Applications" area, select "New Type" and enter:

    5. Description of type: PDF
      File extension: PDF
      MIME type: application/pdf
      Application to use: DKA0:[ADOBEACROBATVIEWER]PDF

      Note: If your viewer directory is not DKA0:[ADOBEACROBATVIEWER], change this value to the correct directory specification. Also note that you can enter the file specification in either OpenVMS or UNIX syntax, or you can use the Choose button to locate your application.
       

    6. Click OK to close the New Type window
    7. Click OK to close the Preferences window
  10. If you have installed Navigator, configure Navigator V3 for OpenVMS for the helper application by following these steps:
    1. Start Navigator
    2. From the menu bar, select "Options" and then "General Preferences...".
    3. In the General Preferences window, select the "Helpers" tab
    4. Select the entry for "application/pdf" and click "Edit..."
    5. In the "Handle By" section, select "Application"
    6. In the text area below Application, enter:

    7. @DKA0:[ADOBEACROBATVIEWER]PDF %s

      Note: If your viewer directory is not DKA0:[ADOBEACROBATVIEWER], change this value to the correct directory specification.
       

    8. Click OK to close the Helper window
    9. Click OK to close the General Preferences window

Printing

Network printing is not supported by the Adobe Acrobat Viewer (for Java).  Users wishing to print PDF files are encouraged to do so from another platform.

Tuning

Display is too high
If you are using the traditional X Window System desktop (rather than the Common Desktop Environment [CDE] desktop), the initial Viewer window may display too high on the screen, and the top of the window may not be visible.  This is a known problem with JDK V1.1.8.  If you cannot reach the top of the window to pull it down, position your pointer on the window and press Alt + F7, causing the pointer to change to a four-headed arrow.  You can then pull the window outline to the desired position; and click the mouse button (MB1) to finish the move.

Missing Fonts cause FTP request
When the Viewer opens a document that uses fonts that are not part of the installation package and that are not embedded in the document,  the default action by the Viewer is to attempt to connect to Adobe using FTP (if you have TCP/IP installed and running) and to download the font.  The Viewer does this each time you open the document because there is no local caching of these fonts.  If you need to access a firewall or proxy to enable FTP, use the Viewer's preferences menu to set this attribute.

If you have TCP/IP running but do not want the Viewer to access the Adobe site each time you open a document, specify a local font directory in the Preferences dialog of the Acrobat Fonts tab.  Specifying the local font directory can be difficult because the fields in this window do not display properly.  However, if you enter the data here, you can point the Viewer to something other than the Adobe FTP site.

You have the option of using DECwindows fonts. You can edit the ACROBAT.PROPERTIES file to include the line that directs the Viewer to a different directory.  For example, the following line points to a directory ([sys$common.fonts]) with DECwindows fonts:

com.adobe.acrobat.fontsource=file://localhost/sys$common.fonts/decw/100dpi

This should stop the Viewer from using FTP to download fonts.

Disabling FTP Font Request at Individual Workstation
You can check to if the FTP site has been specified for a missing fonts and disable this specification.  Perform the following steps:

  1. Select Preferences from the File Menu.
  2. Click the Acrobat Fonts Button.
  3. Check the URL listed on the page that appears.
  4. Remove the FTP directory.
Once you have accomplished this,  the Viewer substitutes a font that is similar to the missing font, instead of going to the ftp directory.

Troubleshooting

Out-of-memory warning
If you read very large documents or zoom in too far, you may receive an out-of-memory warning.  If this occurs, increase the amount of memory in the -mx32m option, which,  in turn, may require you to increase the page file quota.  For example, the following command opens an Alpha system configuration document with sufficient memory to zoom in by a factor of 400%:

$ java -mx48m "com.adobe.acrobat.Viewer" GEA00KPF.PDF

You may need to increase the pagefile quota to 160000 or higher.

File is damaged or not PDF format
If you transfer files to your system and the transfer is not in binary format, or if you use a web browser to download and save the files, the files may not be in the correct format.   If the Viewer gives you an error message saying the file is damaged or not in PDF format, get a full directory listing of the file, and, if necessary, use the same SET FILE /ATTRIBUTES command given in the Downloading section to set the file to Stream_LF.  The recommended format for PDF files is Stream_LF.    If this does not correct the problem, then the file may have been damaged by the change in format, or may not have been transferred as a binary file.   Transfer the file again, possibly using another transfer method.

Fixed-length records may not work
Some programs that read PDF files may also accept files that have fixed-length records of exactly 512 bytes, but this may not work with this Viewer.  In this case, you will not be able to read the file.

Unable to find the directory
During installation, if you receive the following error, check the definition of CLASSPATH and make sure it is in all lowercase:

Unable to find the directory 'locales/' in the Zip file
 



© 2000 Compaq Computer Corporation.
COMPAQ, the Compaq logo, VAX and VMS Registered in U.S. Patent and Trademark Office.
Alpha and OpenVMS are trademarks of Compaq Information Technologies Group, L.P.
All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.
Compaq shall not be liable for technical or editorial errors or omissions contained  herein. The information in this document is subject to change without notice.