• Acquisition and Installation

  
  Note: If you are reading this from within PLCash's help system, you may wonder what purpose this page serves, since PLCash is already installed and running. Well, this documentation set is also available on the Web to guide new PLCash acquirers. Also, some parts of this procedure may be worthwhile to review after installation.
  • Acquisition
    • The most recent version of PLCash is available from the official PLCash Home Page located at http://www.arachnoid.com/PLCash.
    • Acquire the program in one of two forms:
      • A Windows executable if you are running any current version of Windows (Windows 98 to present).
      • A Java Archive (JAR) if you are running any other operating system.
    • Acquire an appropriate Java runtime engine, required to run PLCash, from http://java.sun.com.
      • Any Java Runtime Engine (JVM) from the Sun download site newer than version 1.4 will successfully run PLCash.
  • Installation
    • Install Java
      • Installing Java requires different procedures on different platforms. The Sun Java download site ( http://java.sun.com ) offers complete documentation on this procedure. Be sure to install Java before trying to run PLCash.
    • Install PLCash
      • Windows:
        • Just run the downloaded executable installer. It will guide you through the process.
        • Important note: If you have one of several kinds of ZIP utility programs, you may have to remove them from your system or disable their association with JAR files before installing PLCash. Many of these programs are being overly aggressive in reserving to themselves exclusive control over JAR files, which are Java executables and must be the exclusive preserve of the Java runtime engine. If left uncontrolled, these misbehaving ZIP utility programs may prevent PLCash fron running at all.
      • Other operating systems (Linux, Macintosh with X, OS/2, any systems for which a Java runtime 1.4 or better is available):
        • Place the PLCash JAR file in any suitable location, Linux example /usr/local/bin.
        • For access in X Windows, you may make a shortcut to your desktop, or simply run the program from its installed location the first time. Once you have run PLCash, you can use a program feature to make desktop shortcuts for you (File ... Make Desktop Icons). The resulting icon should look like this:
  • First Run
    • The first time PLCash is run, it creates a new directory under your user directory named ".PLCash". Hereafter I will refer to this location as (user directory)/.PLCash. The actual location of this directory differs from system to system. To find out where this directory is located on your system, click the "About" button at the extreme right end of the PLCash toolbar.
    • PLCash makes a copy of its documentation files (these pages) at (user directory)/.PLCash/Documentation. This local copy of the documentation set is needed to allow your system Web browser to find it.
    • PLCash stores all its data files (your financial records) at (user directory)/.PLCash/data. Be sure you know where this directory is located (its location is also given using the "About" program feature) and make sure to regularly back up your data files from this directory.
  • In the event of difficulty
    • If you have Windows and clicking the provided PLCash icon makes Windows ask which application is associated with JAR files, please install the Java runtime engine before trying again (see above).
    • If you have Windows and clicking the provided PLCash icon causes a ZIP/UnZIP utility to run, remove that utility from your system, reinstall Java, and try again.
      • Note: Programs that hijack the JAR file suffix are essentially cyber-criminals. The JAR suffix is reserved to the Java runtime engine, and any programs that try to reserve it to themselves are written by petty criminals who should be cast out of the Internet community. Take the first righteous step — remove the ZIP/UnZIP program from your system and discard it. You will have to reinstall Java before trying again.
    • If you click a PLCash program icon and nothing happens:
      • Open a DOS window (Linux: command-line shell), maneuver to the directory containing the PLCash.jar executable file and type: "java -jar PLCash.jar". Any error messages that appear may be able to guide you to a solution. Be sure to also look into the PLCash error log, located at (user directory)/.PLCash/PLCashErrorLog.txt, for messages that may help reveal the problem.
      • For the purpose of reporting program bugs, not for routine installation help, post a message at http://www.arachnoid.com/messages. If you submit a bug report, be sure to include the error log located at (user directory)/.PLCash/PLCashErrorLog.txt, even if there are no errors listed below the dashed line.
  • Preliminary Configuration
    • Once you have PLCash running, a useful first step is to find any system browser you may have. PLCash has an internal browser but it is not particularly advanced and it is primarily available for those who don't have a system browser. You are better off allowing PLCash to locate an external browser on your system. Here's how:
      • Choose menu item "Tools ... Setup External Browser."
      • The browser configuration dialog will appear at the bottom of the display.
      • In most cases, the default settings will be appropriate. Click the "Go" button. A search will commence.
      • With any luck, and assuming your system has a Web browser, this search algorithm will locate it. If so, press "Continue".
      • If the search turns up nothing, you may have to provide additional hints:
        • If the name of your your Web browser's executable doesn't appear in the list of browser names, add it. Example: "mozilla.exe", and check to make sure you know what your browser's executable name is.
        • If you know in which directory your browser is located and that directory path is not part of the default path set, add it to the list (or replace the existing list). If you want the search to examine multiple paths, separate them with semicolons. Example: "/usr/bin;/usr/local/bin".

        • If you must include a drive letter in your path, make sure the drive letter is entered as an uppercase character: "C:/Program Files".

        • If you find that your browser will not display pages properly and your operationg system uses drive letters, as a last resort try moving your browser and PLCash onto the same partition to avoid the use of drive letters. Also, if your operating system uses reverse slashes instead of forward slashes, use forward slashes.
      • In extreme cases, to get around this entire process, exit PLCash and edit the file (user directory)/.PLCash/PLCash.ini.
        • Find the line marked "Located Browsers".
        • Add a browser name and full path including the name of the executable, like this: "Browser Name|Full path". Example entry: "Mozilla|/path/more_path/mozilla.exe". Notice that forward slashes are used, and the actual executable name is used.
        • You can add as many of these entries as you like, separated by commas: "Browser1|Path1,Browser2|Path2", etc..
        • While editing this file, look at the other settings. You are free to edit any of them you need to, in order to customize PLCash in ways not explicitly provided for (and in ways I may not have thought of). While you read the list, think — why don't Windows programs allow this sort of flexibility? The answer, of course, is that Windows programs are designed to control you, not the reverse.

Now you are ready to use PLCash.