v1541commander -- frequently asked questions
============================================

This document contains actual questions asked by the users and might be
updated from time to time.


1. About the BAM
----------------

Q: What does an "invalid BAM" mean?

A: On a 1541 disk, the BAM (block availability map) stores which sectors (or
   blocks) are used by files and which are available. It also stores the
   number of available blocks per track.

   When V1541Commander opens a disk, it tries to read a CBM DOS filesystem
   from it and doing this, the BAM is validated. First, it is checked whether
   the available blocks per track actually match the BAM data. It is also
   acceptable if this number is 0 for *all* tracks, because there are disks
   using this to report a fake "0 blocks free." line.

   Then, the BAM data is compared to the blocks actually used by the
   directory and files found on the disk. This check will fail if there are
   things on the disk V1541Commander doesn't know, like for example
   trackloaders, C128 boot sectors, GEOS files, etc.

   When the BAM is found to be invalid, V1541Commander suggests to treat the
   image as a "new" image, so you don't accidentally overwrite your original
   image when saving after making some changes.


Q: What happens when I edit a disk with an "invalid BAM"?

A: This depends on how the BAM is invalid. If there are some additional blocks
   marked as used, you just can't use these when writing files. If some blocks
   actually used by files are marked "available", writing files to this disk
   *could* overwrite these blocks, destroying other files.

   It's probably best to save your edited disk as a new image and thoroughly
   test it.


Q: How can I fix an "invalid BAM"?

A: Use "rewrite image" from the "CBM DOS" menu. But be warned that this
   creates a new disk image from the current filesystem. Any data
   V1541Commander doesn't understand (like trackloaders, C128 boot sectors,
   etc) will be missing on the disk after rewriting the image.


2. Broken filesystem and recovery mode
--------------------------------------

Q: What is a broken filesystem?

A: A filesystem stored on a 1541 disk can have some severe consistency
   problems. A typical problem would be a sector that is used twice (e.g.
   by the directory and a file, or by two different files). If such a problem
   is found, V1541Commander tells you the filesystem is broken and will be
   opened in recovery mode. The default action is to rewrite the image
   directly after opening, so you have a clean image with the data that could
   be recovered, but you can disable this.


Q: What does open in recovery mode mean?

A: Recovery mode is automatically used to open a filesystem from a disk image
   when severe problems with the filesystem are found. In recovery mode,
   V1541Commander tries to read as much file data as possible, while avoiding
   to read a sector twice. There is no guarantee that everything can be read.


Q: Can I edit a broken filesystem?

A: Short answer: no. A broken filesystem will be read-only. But you can copy
   files from it to another disk image or to your file manager using
   drag&drop. Of course, you can rewrite the disk image to get a new, clean
   image from whatever was successfully read, and then you can fully edit
   the image. Be aware you might lose data doing this.


Q: I downloaded a Zipcode compressed disk and V1541Commander tells me it has
   a broken filesystem, what should I do?

A: In most cases, your download is probably fine. Even a broken filesystem
   *could* work flawlessly for reading on a 1541 drive. To save the extracted
   image without any changes, do the following:
   - In the options dialog popping up, uncheck the checkbox saying to rewrite
     the image after recovery.
   - Then, save the disk from the file menu (or by hitting Ctrl+S).
   - Answer yes to the safety question asking you whether you really want to
     save an image with a broken filesystem.
   This process will save the exact image that was found in the Zipcode files.


3. Official builds
------------------

Q: My virus scanner reports V1541Commander to be infected / be malware / eat
   my cat / ... ?

A: Virus scanners use heuristics, so "false positives" happen all the time.
   If you downloaded your copy from csdb.dk (released by "Excess"), you can be
   very sure there is no virus. The only risk would be someone hacked csdb and
   tampered with the files there ...

   Official releases are built on a FreeBSD machine using GNU GCC-based cross-
   compilers for Windows and Linux, you can see the scripts used in the git
   repository. Still, if you don't trust our official builds, you can always
   build your own from the source :)


Q: But why does a virus scanner think there is some malware?

A: Most likely, one of the heuristics used by the scanner found a pattern that
   resembles something used in malware before. Unfortunately, this can't be
   fully avoided. At the time of the V1.1 release, the official windows build
   was checked at virustotal.com, with one out of 70 virus scanners (falsely!)
   reporting some malware.

   If you use an older virus scanner, it's also possible that your scanner
   thinks the cruncher used on the official builds (UPX) is suspicious. This
   isn't an issue any more with recent AV software, they all know UPX and will
   scan the decrunched executable.


Q: Why are the official builds crunched?

A: The official builds use static linking. This means all libraries used are
   embedded in the executable. Static linking is a good way to ensure the
   program runs on any system without problems and doesn't require
   installation. An alternative would be to ship all required libraries (DLLs
   on Windows) with the executable, but this would even take up more space.
   Static linking also ensures the executable is self-contained, so it will
   work no matter where you put it, not requiring any additional files.

   Still, a statically linked executable is quite large and a cruncher can
   drastically reduce the size. At the time of writing, the Windows build of
   V1541Commander has around 14.5 MB uncrunched, but only 5.1 MB crunched.
   Given today's standards, this doesn't sound like much, but imagine you want
   to carry your copy of V1541Commander on your USB key ...


Q: Doesn't crunching have drawbacks?

A: In short: no, not for V1541Commander. There are several typical drawbacks:

   - decrunching takes time: Well, this isn't an issue nowadays. Decrunching 
     a few MB happens faster than you can look on your typical PC, you won't
     be able to notice.

   - decrunching needs more RAM: This depends on the cruncher. UPX decrunches
     "in place" (just like the famous exomizer for the C64 does), so it
     doesn't need any additional RAM.

   - multiple instances of crunched programs can't share the memory pages for
     code: This is actually true. If you run multiple copies of a program on
     a modern OS, the OS knows the code is the same and keeps it in RAM only
     once. This won't work with decrunched code because it's changed compared
     to the code on disk. But V1541Commander is designed as a "single
     instance" application: Any second instance will just talk to the already
     running one and immediately quit. So, this isn't a drawback for
     V1541Commander.

   - virus scanners consider crunched programs suspicious: At least for
     programs crunched with UPX, this is a thing from the past. Nowadays, all
     major virus scanners know UPX and decrunch before scanning. If your virus
     scanner is unhappy with V1541Commander, consider to upgrade.

