Frequently Asked Questions (ASM2)

How do I import my existing database to

After signing up for an account on, you may want to get your existing database imported.

All you need to do is email a copy of the database files to the administrator at, including your account number

There are five files required from your original database:

    localdb.backup (this file may not be present, just ignore if you don't have it)

You can find these files in:

Windows Vista, 7, 8 and 10: C:\Users\YOURUSER\.asm

Windows XP and 2000: C:\Documents and Settings\YOURUSER\.asm

Mac OS X: /Users/YOURUSER/.asm

Linux: /home/YOURUSER/.asm

How do I move my ASM data to another computer or backup my data?

All ASM data is stored in a group of 4 files that start with localdb in the .asm folder in the user's home directory.

On Windows XP, this folder is Documents and Settings\YOURUSER\.asm, on Windows Vista and 7, this folder is Users\YOURUSER\.asm.

For Mac it's /Users/YOURUSER/.asm and for Linux and other Unix variants, it's /home/YOURUSER/.asm

You can install ASM on another computer, run it to get a blank database and things set up for that user and then copy those localdb files from another computer to transfer the data.

You can also use this technique to take a backup of the data files and restore them on the same computer if you need to.

Note: ASM should NOT be running when you copy the data.

How do I add new locations or species?

All lookup data (including locations) can be edited under System→Lookups.

How do I import my data from into ASM2?

1. In, export your data to a file by going to Settings→SQL Interface→Export→SQL Dump (ASM2 HSQLDB Format)
2. Download and install ASM2 from our website - Download
3. Run it to create a new local database
4. In ASM2, go to System→Database Tools→Run Database Update
5. Select the dump file you downloaded to load your data into ASM2

How do I enable debug mode?

ASM has a debug mode that allows you to copy databases, produce database dumps and get additional info while ASM is running to help diagnose problems.

To do this:


1. Right click on the "Animal Shelter Manager" shortcut on your desktop and pick Copy. Right click again on the desktop and click paste to make a copy of the shortcut.
2. Right click on the copy of the shortcut and pick Properties
3. In the target box, add -Dasm.log.debug=true after the java call in the file, eg:

"C:\Program Files\ASM\Java\bin\javaw.exe" -Dasm.log.debug=true "-cp..

4. Double click the shortcut copy to start ASM with debug information and options on.


Edit the script and add -Dasm.log.debug=true after the java call.


Edit /Applications/ and add -Dasm.log.debug=true after java.

I've forgotten my password, can I reset it?

You can't reset your password from inside ASM, but you can connect to the database to reset it:

1. Make sure ASM is closed
2. Open "Local Database Manager" from Start→Programs→Animal Shelter Manager
3. Copy the following text into the execute box, substituting YOURUSERNAME for the username
you'd like to reset the password for (make sure that it still appears in single quotes, eg: 'james')

    UPDATE users SET Password = 'd107d09f5bbe40cade3de5c71e9e9b7' WHERE UserName = 'YOURUSERNAME'

4. Press the execute button
5. Go the Command menu and pick "CHECKPOINT", then press the execute button
6. Close the local database manager

Your password has now been reset to 'letmein'.

How do I completely uninstall or reset ASM?

Any local database and all settings for ASM are stored in the .asm folder, found in your home directory.

On Windows XP, it's Documents and Settings\YOURUSER\.asm
On Vista and Windows 7 it's Users\YOURUSER\.asm
For all Unixes, it's $HOME/.asm
For MacOSX, it's /Users/YOURUSER/.asm

Removing that folder effectively resets ASM to being a brand new installation.

How do I produce a database independent dump file?

Data dump files can be used to port your data from one version of ASM to another and between different types of databases.

1. Enable debug mode by following this FAQ

2. Go to System→Database Tools→Database Dump

The system will prompt you to include media files. Do this if you have and want to include
animal photographs. This will increase the size of the dump file.

3. The dump file is output into $HOME. ASM will give you the final location in a dialog on completion.

Databaseversion flag couldn't be read

ASM2 keeps all its configuration in RAM and when you save on the options screen, it starts to trickle the changes through to the database.

If something goes wrong and the program is killed (power outage, computer crash, etc), it can leave the database in a state where the DatabaseVersion flag no longer exists in the config.

To fix this (Windows, local database) go to Start→Animal Shelter Manager→Local Database Manager

In the query box, put the following:

    INSERT INTO configuration VALUES ('DatabaseVersion', '2870')

then press the Execute button. Once you have an ok response, close the database manager and restart ASM.


For other platforms and databases, run the query at the appropriate console.

An instance is already running

The "allow only one instance" option is set under Preferences→Settings

To clear the lock file, go to Documents and Settings/YOURUSER/.asm in Windows Explorer
and delete the file called "lock".

for MacOSX and Linux: rm ~/.asm/lock

Trying to open ASM I get "user lacks privilege or object not found: DBFS"

Corruption can remove the DBFS table from your database. To fix this, you'll need to open the .asm/localdb.script file with a text editor. Windows users can find the file in C:\Users\YOURUSER\.asm, Mac users in /Users/.asm and Linux users in /home/YOURUSER/.asm

Open the file and search for the line "CREATE INDEX DBFS_PATH ON PUBLIC.DBFS(PATH)"

Above this line, add a new line:


Now, find the broken index line for DBFS that looks like this:

    SET TABLE PUBLIC.DBFS INDEX '2963064 1617192 2554032 0 0 0 135'

Delete that line and save your localdb.script file.


Sometimes, the HSQLDB driver can miscalculate the amount of memory required when indexing data in the dbfs table. To fix it, you need to edit the localdb.script file in the .asm folder with a text editor (for example, notepad or wordpad on windows, vi on Linux/Mac) and find a line that looks like the following (the numbers will be different):

    SET TABLE DBFS INDEX'2963064 1617192 2554032 0'

Delete this line from the file and save it.

I can't find the .asm folder on my Mac?

The .asm folder is in /Users/YOURUSER/.asm, but finder hides it from you. You can add a visible link to it by going to /Applications/Utilities and opening the Terminal app and entering the following:

    ln -s .asm asm

This will make your Mac refer to the .asm folder as just asm in your home folder and it will appear in Finder.

I get "ASM user doesn't match OS user"

You've enabled the option for OS security. OS security relies on you having an ASM user in the database that has the same name as the user you're logged into your computer as.

This message occurs when ASM couldn't find a user in its database for the user that is currently logged into the OS. To fix it, you can disable OS security by using the following query:

    DELETE FROM configuration WHERE ItemName Like 'AutoLoginOSUsers'

You can run the query from the local database manager tool that comes with ASM.

Windows: Opening the Local Database Manager tool from ASM's group in the start menu

Mac: open Finder, go to /Applications/Utilities and open the Terminal application. At the prompt, type the following and press return to get the local database manager utility:


(this assumes you put ASM in your /Applications folder).

Paste the query in the box and hit the Execute button. When you've done, delete everything in the box and replace it with the word CHECKPOINT and then hit Execute again. You can now close the database manager and reopen ASM.

Can I use MySQL for the database?

Yes. To use MySQL, you'll need to install MySQL 5.0 or newer on the target platform of your choice.

Once you've done this, get an SQL console and create a new database for ASM.


Next, use the SOURCE command to run the mysql.sql file that ships with ASM. On Windows, it's in Program Files\ASM\sql

    SOURCE mysql.sql;

Use the SOURCE command again to run the appropriate translation file for your language.
You can find the translation sql files in the same location you found the mysql.sql file.

    SOURCE translate_en.sql;

If you are using a graphical MySQL tool (such as phpMyAdmin or the enterprise manager tools that comes with the Windows installation of MySQL), you can create the database and open/run the mysql.sql and translate_*.sql files without needing to type commands at a console.

Once this is done, your database is ready and you can use the Preferences→Switch Database option in ASM to select MySQL as the database type, complete the hostname of the machine running MySQL, the database name, username and password. Leave password blank if you didn't set one for the user.

Note that for many installations of MySQL, you will have to create a user account that is allowed to access the database from outside the local machine. You can do this by running:

    GRANT ALL ON asm.* TO asmuser@'%' IDENTIFIED BY 'testing';

This will create a user called "asmuser" with the password "testing" that has permissions to access the database called "asm" from any machine on the network.

How do I control what application ASM uses to open files?

By default, ASM asks your operating system to open files and should use whatever programs the OS has set for editing.

You can override this behaviour by adding a new parameter to the shortcut that starts ASM.


1. Right click on the Animal Shelter Manager shortcut and pick properties
2. In the shortcut, add the switch -Dasm.shellexecute=internal so it looks something like:

"C:\Program Files\ASM\Java\bin\javaw.exe" -Dasm.shellexecute=internal "-cp etc...

1. Edit the /usr/share/asm/ file
2. Add -Dasm.shellexecute=internal after java in the file


1. Edit the /Appliations/ file
2. Add -Dasm.shellexecute=internal after java is launched in the file

See the chapter in the manual on system properties.

Once you have set this property, a new option will appear under the Preferences menu for "Configure File Types", allowing you to configure which programs are used to open files of a particular extension.

How do I network my data?

If you're using the default, local database, you can do the following to allow other ASM clients on your network to use your data:

1. Make sure ASM is closed on your computer

2. Run the "Local Database Server" shortcut from Programs→Animal Shelter Manager (for Windows, MacOSX and Unix users can run the script). Note, you will have to run this each time you start up your computer - you can copy this shortcut to Programs→Startup to have Windows do it for you. Once you've started the database server, you can open ASM on the computer running the server if you want.

3. Install ASM on your other computers. When asked where the database is, hit the Scan button at the bottom right - after a short wait, details of your server will be completed and you can hit Ok to connect and continue (ASM will remember and use this database in future). If you already had ASM installed with a local database, use the ``Switch Database'' option under the Preferences menu to switch to your database server and use the Scan button.

I get "Out of memory" errors sometimes when running ASM

You can instruct ASM to utilise more memory by doing the following:


1. Right click on the ASM shortcut on your desktop and choose properties
2. Add -Dasm.ram=512 to the shortcut, so it looks something like this:

"C:\Program Files\ASM\java\bin\javaw.exe" -Dasm.ram=512 -cp "C:\Program Files\ASM\asm.jar" net.sourceforge.sheltermanager.asm.startup.WindowsBoot "C:\Program Files\ASM"


1. Edit the /usr/share/asm/ file and change the -Xmx256m to -Xmx512m

I get "Out of memory" errors when starting ASM

If you are using the local database, it's possible that the file can get corrupted, causing the message "Out of memory on script line X" to appear when starting ASM.

In older versions of ASM, the file contained all of the data. In more recent versions (2.3.0 onwards), it just contains the media files.

MAKE A COPY OF ALL YOUR DATA FILES BEFORE ATTEMPTING THIS REPAIR PROCEDURE. Take copies of the four localdb files (, localdb.backup, localdb.script, before following any further instructions.


1. Go to Users\YOURUSER\.asm and delete the file
2. Right click and create a new text file
3. Rename the text file to (so we've created an empty file with the same name)
4. Edit and set the modified=no line to modified=yes and save it
5. Start ASM


1. Open a terminal
2. Run "rm .asm/"
3. Run "touch .asm/"
4. Edit .asm/ and set the modified=no line to modified=yes and save it
5. Start ASM

The ASM applet is unusable on my Mac

The ASM applet does not work with Safari in 64-bit mode. You need to run Safari in 32-bit mode to use the ASM applet.

Apple have also removed Java from later versions of OSX and the Java shipped with 10.3
and earlier is not new enough. Generally, it's best to use ASM3 if you can with your Mac.

Is it possible to have multiple databases?

There are lots of ways, but probably the simplest is to maintain a different database for each.

The easiest way to get separate databases is to create another user account on your computer. Since ASM stores its database in the profile of the logged in user, all you have to do is add a new one, log in as it, fire up ASM and you'll have a different database when logged in as that user.

Which OS/platform are supported for ASM and the database?

The software is built with Java. The database can be either HSQLDB, MySQL or PostgreSQL. Pre-built installers are supplied for MacOSX, Unix, Windows, Linux/Deb and Linux/RPM.