The PIN file

As we saw in Figure 2, “The PIN file dialog.”, Patchworks requires an input file at startup. The input file is called a "PIN" file (Patchworks INput file). It has three main functions:

Some sections are required and others can be customized to create maps and reports particular to your needs. The PIN file contains declarations and programming commands that are specified in a Java-like language known as BeanShell. This fully structured programming language can include conditional statements, loops and subroutines. All names, labels, attributes, accounts and targets can be set the way you want for each analysis.

The programming commands in the PIN file are loaded and interpreted when the Patchworks program is started (see the section called “Starting Patchworks” for complete Start Up instructions). If you edit the PIN file, your changes will not take effect until the next time you start Patchworks. It is often the case that the PIN file only needs to be set up once for an analysis. Once a correctly configured PIN file has been created, the interactive controls in Patchworks can be used to generate a wide range of scenarios.

If the PIN file contains an error (such as a misspelt keyword, or incorrect syntax), the Patchworks program will display an error message during loading, providing a hint as to the cause of the error. You should correct the error and restart the program.


Do not attempt to perform an analysis after receiving an error message while loading the PIN file! The loading process will not have completed successfully and the model may be in an inconsistent state.

Since you'll need to create a PIN file right away to begin, Patchworks includes a wizard called the PIN Builder which will build a basic PIN file which you can then edit and customize. The PIN builder is accessed from the Application Launcher in the "Data Prep" folder.

Figure 55. Access to PIN Builder from Application Chooser

When this wizard is activated, several panes will come up and ask for the following:

Figure 56. Dialog boxes within the PIN builder

  1. location to store the finished PIN file. This will be the folder where you would like to save the completed PIN file. The actual file name will be chosen when you save the file at the end of the wizard.

  2. planning period width and number of planning horizons,

  3. location of the directory containing all of the tracks datasets, and the name of the block shape file,

  4. the attribute used as the block label in the block shape file.

Upon clicking "Finish" the PIN builder will give you the option of choosing some additional file elements, such as groups, topology, patches and roads, these are explained fully in the section called “Group Summary Accounts”, the section called “Creating patch account definitions using the PIN Builder”, the section called “Setting up route accounts using the PIN Builder”. It is not necessary to add these components to create a working PIN file. After adding them, however, your window will look like this:

Figure 57. Adding additional code to the PIN file

When you click on "Show Code", the resultant file will contain all the code necessary to load a Patchworks model. If you added patch and road targets, suggested map layers and reports for patches and roads will be added in the appropriate PIN file sections. Other default (typical) map layers and reports are also included. Here is your chance to save the generated PIN file by choosing the "Save" option under the file menu, or by copying and pasting selected sections.

In this file, the three main sections are:

The Patchworks Class Library API Reference manual can be used to draw upon a library of routines (classes and methods) to do all of the PIN file tasks.

The following section will explain the general features of the "Global Variables" section. Other sections of the PIN file are explained in other chapters. For information on adding group accounts to the PIN file see the section called “Loading Group Accounts in the PIN File”. To find out how to add patch accounts to the PIN file, go to the section called “Add patch account code to the PIN file”. To see how to set up route accounts in the PIN file go to the section called “Route Accounts”.