README file for CDB 1.0 ALPHA release #8 (1/15/97) SUMMARY CDB is a powerful positional chess database program. It imports and exports PGN and can be used as a PGN browser. If Crafty is installed on your computer, CDB can invoke Crafty for analysis of positions and games. NEW FEATURES - Variations in games - Addition of Crafty principal variations (PVs) as variations to games rather than as textual annotations - Positional "flashcards" - User control over name aliasing, name normalization, and duplicate game merging - Editing of game tags (with automatic gameset recalculation) - New simple command for loading custom piece bitmaps - New ECOtree.pgn file replaces cdb-eco.pgn - Many bugfixes, including: - BUG: Deleting a note causes a crash - BUG: Don't auto-select an imported game if the user is browsing in the view. - BUG: Bad cursor in piece setup menu - BUG: Nonstandard moves like Kab7 not accepted - BUG: Can't handle wild games that ICC transmits with a FEN of "under construction" - BUG: Moves from Crafty's game PV aren't showing up on chessbd - BUG: Chessboard Setup->Clear doesn't erase arrows - BUG: Legal moves arrows should be off by default - BUG: CDB doesn't come up on top of other windows - BUG: Seems to be too many invalidations when initializing; window flashes - BUG: Weird scoresheet scrolling - BUG: No move annotations in Known Moves window RECENT FEATURES - Clipboard cut/copy/paste of PGN games - Configurable chessboard colors - Moveable and resizeable controls - Game addition to and removal from gamesets - An automatic "Selected Games" gameset useful for bookmarking - Board setup mode - Nonstandard "suicide" and "wild" chess support - Crafty 14.3 support - Most preferences now saved in Registry - Larger temporary databases - Creation of subset databases from gamesets - Faster algorithm for game searches from positions OVERVIEW CDB builds databases of chess games, variations, and positions. Each distinct position that arises in any game is represented exactly once in the database. Most positions can be represented in an extremely compact form (12 bytes), which works out to roughly 1Kbytes per game for downloaded PGN. When browsing through positions, all known moves to and from the position are available, as are game statistics. New games can be added to the database from the user interface and by importing PGN (portable game notation) files. Positions can be annotated. The PGN parser is robust and can cope with some (not all) of the problems seen in PGN files available for download from the Internet. CDB can be used directly as a PGN browser; in this mode, CDB saves nothing to disk unless explicitly commanded to establish a database. CDB databases are initially maintained in virtual memory and exist only for the session. Such databases are useful for examining the contents of PGN files, but are limited in their maximum size. Databases can be saved permanently on disk and then are accessed and modified as memory-mapped files. Typical usage of CDB is to enter a game or import a PGN file, then use the Establish command of the File menu to create a permanent database that can be accessed in a later session via the Use command. CDB supports a concept of "gamesets", which are collections of games. Gamesets are created for each input source and database query. Gamesets can be combined, restricted, used to find games, and used to select multiple games for PGN export. CDB can now also interface with Bob Hyatt's Crafty 14.2/14.3 (available from ftp.cis.uab.edu in /pub/hyatt) for positional analysis and game analysis! CDB now supports databases of nonstandard games, such as FICS "Suicide" games, in which pawns can promote to Kings, Kings can be captured, stay in check, or move into check, etc. DISCLAIMER CDB was built with (and, to some degree, despite) Microsoft Visual C++ 4.0 and MFC for Windows 95. It runs well on a machine with 133MHz Pentium, 256KB external cache, and 40MB of DRAM; machines with less memory will not perform as well when modifying large databases, though closing other applications may help. No other platforms are currently planned to be supported, nor any other packaging of the database technology (such as in a DLL). CDB was written primarily for the author's own use and has been made available to the public without charge, support, or any guarantee of usability out of gratitude for other useful free chess software written and operated by others, especially the Free Internet Chess Server. CDB is a work in progress and updated versions will be uploaded to the internet occasionally as they are prepared. Updated versions are not guaranteed or likely to be compatible with older databases and documents, so back up your work as described below or suffer annoying consequences. The author, Peter Klausler of Minneapolis, Minnesota, retains all rights to the program, its source code, and the inventions therein. CDB is not meant to compete with commercial chess database products. If you find CDB to be useful, you may want to consider trying a professional-grade product with support, documentation, installation tools, and high-quality annotated content. If you find CDB not to be useful, a commercial database product will probably suit you better. Support good chess software! Comments, suggestions, bugs, and kudos can be sent to the author by messaging "pmk" on FICS or ICC, or by e-mail (ask for address). Check pmk's finger notes for news of updated versions of CDB. If you like CDB, why not tell others about it via rec.games.chess.misc or shouts on your favorite chess server? INSTALLING CDB AND ESTABLISHING A DATABASE * Run CDB and build a permanent database via "File->SaveAs" to create an empty database file. * If you tell the Windows shell that "*.cdb" files are to be opened with CDB, you can resume working with the database simply by double-clicking its icon. And unless you prefer another PGN browser program, tell Windows to use CDB for "*.pgn" files too. * To display ECO codes and opening names in your new database, use "File->Import PGN" and import the "ECOtree.pgn" file, which you should download from the site where you acquired CDB itself. This file contains a bunch of position annotations adapted from somebody else's downloadable file on FICS (whom I would acknowledge if I knew their identity!). * Go download a pile of PGN files from: ftp://fics.onenet.net/chess/PGN ftp://ftp.pitt.edu/group/chess/PGN http://www.chesscenter.com/twic/twic.html and a myriad of other sites. If you use the BlitzIn interface to ICC, it can be configured to save a log of your games in PGN format. Internet chess servers like FICS and ICC can also mail you the moves of your games automatically in PGN format if you want, too; CDB can read saved e-mail files and extract the PGN. Since CDB detects duplicate games automatically, you can import the same file multiple times into the same database to just pick up the new games, which is helpful with interface log files. * You might want to set up just one huge database with every game you can get your hands on, or maybe you'll want to set up one database for your own games, one of historical games, one of recent games, etc. The advantage of one database is that everything's together; multiple smaller databases, however, are faster. The choice may depend on the amount of memory in your system. * If you don't have Crafty, you should get it. Set up a C:\Crafty directory, then go to ftp.cis.uab.edu/pub/hyatt and download Crafty 14.2 or 14.3, then follow its directions. Using Crafty with CDB is optional but highly useful. HOW TO USE CDB * To use CDB as a PGN file browser, use it to open a PGN file via the Windows shell or via "File->Open". In this mode, CDB will not save anything to disk (and will not prompt you to do so when you exit) unless you establish a database with "File->Save As". If you register CDB as the program associated with ".pgn" files with the Windows shell, you can use CDB to view PGN files directly from a browser or from a decompression program like PKUNZIP. CDB uses its own custom PGN file parser and is very tolerant of the strange things one can find in downloaded PGN files. It automatically ignores things that aren't part of PGN games, like e-mail headers and crosstables. CDB's PGN export routine adheres to the PGN standard. A good way to clean up a sloppy PGN file is to import it into CDB and then export it to another file. CDB will detect illegal moves, bad move numbers, and other problems and prompt you to save a bad game to a file (so you can fix it with a text editor), skip a bad game, or abort reading the rest of the file. Help stamp out bad PGN on the Internet. * To use CDB on nonstandard chess games (such as FICS "suicide" or ICC "wild17" games), initialize your database with the "File->New Nonstandard" command before importing any files or entering one of your crazy games. I don't play nonstandard chess myself, so watch out for bugs in this mode, and please report any that you run into. * Use "File->Import PGN" or direct keyboard/mouse data entry to add games to your database. CDB will automatically normalize the names of players ("R Fischer", "Fischer, Rob.", and "Robert J. Fischer" will all be recognized as the same person) and also automatically identify duplicate games. Tags from duplicate games will be combined when appropriate. Both of these features can be disabled if you do not find them to be helpful. * If you don't establish an on-disk database, you'll be limited to a maximum database size of 100MB or so. That's no problem for those times when you want to use CDB as a PGN viewer for files no larger than a few megabytes. * There are four GUI controls, plus the usual menu and a (redundant) toolbar. The chessboard control in the upper left displays the current position. Right-click on the chessboard to get a menu that lets you configure the display to your liking. Move pieces around by left-clicking and dragging them. The colored lines on the chessboard identify legal moves, known prior moves, and known moves from the position. You can adjust the thickness of the lines for better visibility on your display, and you can also turn classes of lines off if they are distracting. The known moves list in the upper right shows all the known moves in the current position. You can click on one to make it happen on the chessboard. Game statistics for each of the moves and the first few words of any annotations are also displayed. Moves that initiate variations in the current game begin with a left parenthesis. The score sheet control in the lower right shows the current sequence of moves. If you are browsing a game, all of the game's moves will be on the scoresheet. Moves up to the current position reflected by the chessboard are in boldface; later moves are grayed out. You can use arrow keys and page up/down to move through the moves in the scoresheet; you can also click on any move to display its corresponding position on the chessboard. If you want, you can enter new moves via the keyboard directly into the scoresheet. Only the keystrokes required to unambiguously determine the move will be necessary; hit TAB to end a move that may otherwise be ambiguous (such as O-O when O-O-O is also legal). Note that CDB uses notation like "cd" for captures by pawns, not "cxd4". If you change an existing move, that move and all later moves are deleted from the scoresheet and you are no longer browsing a game from the database. Last, the notepad control in the lower left displays all annotations for the current position. Annotations are stored with positions in the database and are persistent. The notepad is a standard Windows edit control. You can change the notepad's font via the Edit menu. * To manually add a game into the database, reset the chessboard with the green flag toolbar button, move the men around (or type algebraic notation into the scoresheet), and arrive at the final position of the game. Then use "Game->Save..." to add player information, final result, and so on. NOTE: Games that you enter directly should be exported as PGN files and saved as backups. Every game entered from the keyboard has a Source tag with value "user", and is a member of the automatically created gameset called "Games from user", so it's easy to export just these games. Positional annotations that have been modified from the keyboard can also be saved for backup purposes via another command on the File menu. Back up your work! Even if you never hit a bug in CDB, you will someday want to upgrade to a new and improved version of the program, and the binary databases are not likely to be compatible. So always remain in a position in which you can recreate your database from PGN files! You have been advised and warned! * Use gamesets to search for interesting games and control the games for PGN export. You can make a temporary gameset of games containing the current position quickly via "Game->Select from Position", or make a permanent gameset via "Gameset->New". The criteria you specify will restrict the new gameset. For example, you can create a gameset of "games Fischer lost as White in this position", then browse them or export their PGN. Note that any new games entered or imported into the database will automatically be added to the appropriate gamesets. If you're using CDB to search PGN files, you can establish your search criteria first with a gameset, then import, or do it the other way around; it doesn't matter. Gamesets can be combined when new gamesets are created. Specify the names of two existing gamesets and a combination rule (Union, Intersection, or Subtraction), then any additional constraints on position, players, outcomes, colors, and tags. * Note that castling rights and en-passant possibilities are considered to be part of a CDB position. If you are surprised when two positions that look alike are represented twice in the database, they may differ in these extra attributes (which are not displayed explicitly, but can be deduced from the blue lines representing legal moves). MORE INFORMATION Consult the on-line help in CDB for additional information.