CBASCII and CBASCII/32 Version 1.6c

Status

This program is in the public domain. You may distribute it any way you desire, but please keep this document with the executable.

Program Usage

CBASCII is an MS-DOS executable, and CBASCII/32 is a Win32 (console mode) executable, which take their arguments and options from the command line. To see the command line syntax you can type "CBASCII -?" (or "CBASC32 -?") and the following help information will be shown:

usage: cbascii -e|-i [options] ascii-file database

-e = export (ChessBase to ASCII) -i = import (ASCII to ChessBase)

options:

-F file Output error messages to file, rather than screen

-r x-y specify first and last game to convert

-q quiet

-s strip comments

-S strip variations

export-only options:

-a open ascii-file in "append" mode

-c char|value specify 'comment start' character

-C char|value specify 'comment end' character

-d type specify diagram type (default is "8x8")

-f format specify export format (default is "pgn")

-k Ignore ChessBase game checksum errors

-v char|value specify 'variation start' character

-V char|value specify 'variation end' character

import-only options:

-E don't enforce 180-move limit (for CB-for-Windows/Atari-CB)

-I make errors non-fatal (ignore errors)

-l allow long comments (for CB-for-Windows)

-L line start reading ascii-file at line given (1 onwards)

-t test mode; parse ascii-file without adding to database

If an option accepts an argument, the argument may or may not be separated from the option by a space (i.e. "-v1" "-v 1" are equivalent). Multiple options can be grouped behind a single '-' character as long as any options that expect arguments are the last in the group (i.e. "-eqfcb" and "-e -q -fcb" are equivalent).

Note that either -e or -i must be present on the command line; these are not "options".

Exporting

When converting from ChessBase to ASCII (known as "exporting") CBASCII can produce the ASCII files in one of two different formats:

1. ChessBase-format, in the same way as ChessBase does it itself, except symbols (like "With idea", etc.) are converted to an ASCII representation (which is as yet proprietary) rather than an 8-bit value.
2. Portable Game Notation (PGN)-format. PGN is fast becoming the THE way to represent Chess games in ASCII files.

To select which format to export, use the -f option with an argument of either "pgn", "pgn_no_nag" or "cb". More on "pgn_no_nag" later.

Due to the very poor way in which items in a ChessBase header are mixed-up (for example the source field is expected to contain the event name, the site, the round/game number, and the annotator name), CBASCII has to try to guess what the different elements of the players and source fields mean.

CBASCII makes the following assumptions:

1. The White player name is the string before a '-' in the players field, or if no '-' exists the White player name is the whole of the players field upto the round number.
2. The Black player name is the string after a '-' in the players field, and upto the round number, or if no '-' exists the Black player name doesn't exist.
3. The site and event name is the string upto the round number or annotator name, in the source field.
4. The round number is a string of digits or periods enclosed within parentheses, in the players field or the source field. If CBASCII finds the round number in the players field, it won't look for it in the source field, so if it exists in both fields it will not be removed from the source field. CBASCII also allows round numbers in the format "(m/XXX)", but will not export the "m/" part when exporting to PGN format. Also CBASCII does allow round numbers enclosed within square brackets, although putting round numbers inside square brackets is not to be recommended. Note also that CBASCII specifically checks for a slash "/" before a bracket in order not to convert Chess Informant game references into round numbers (i.e. the "23" in "34/(23)" will not be assumed to be a round number).
5. The annotator name is a string of characters enclosed within square brackets, in the source field.

In 1. and 2., an exception is made if two or more hyphens are found in the players field; in this case the delimiting (delimiting white name from black name) hyphen is chosen as the one after the first comma in the players field.

While exporting the white and black players names, CBASCII will do some limited processing on the names in order to conform more fully with the PGN specification:

1. A space is inserted after a comma.
2. A period is added to single uppercase letters after the comma has been seen.
3. Any underscore characters ('_') are converted to hyphens ('-')

Example:

Players: Ying_Yang,A-Duplain,A

Source: Friendly, Brighton Chess Club (1) [Duplain,A]

Result: d

Year: 1994

ECO: D66

Becomes:

[Event "?"]

[Site "Friendly, Brighton Chess Club"]

[Date "1994.01.19"]

[Round "1"]

[White "Ying-Yang, A."]

[Black "Duplain, A."]

[Result "1/2-1/2"]

[ECO "D66"]

[Annotator "Duplain, A."]

As the site and event name are impossible to distinguish in the source field, without resorting to unmanagable lists of such sites and events, the "Event" tag-pair of a PGN header is never written to by CBASCII, rather all the information goes into the "Site" tag-pair.

The move information is exported in short algebraic notation, with check (+) and mate (#) symbols, followed by any move comments. The default comment delimiter characters can be changed if necessary, by using the -c and -C options. The default comment delimiter characters are:

Format	Comment Start	Comment End
ChessBase-format	<none>	<none>
PGN	{	}

For example to use '{' and '}' in a ChessBase-format ASCII file you would type:

cbascii -e -fcb -c'{' -C'}' ...

To use '<' and '>' you would need to specify the character's value rather than the character itself, as the MS-DOS command interpreter gives special meaning to these characters. Thus:

cbascii -e -fcb -c60 -C62 ...

Note also that some command line interpreters (e.g. the Windows NT CMD.EXE) has other "special characters" in addition to '<' and '>'; in order to use these characters as delimiters you would also need to specify their ASCII value rather than the character themselves.

If you wish to have no comment delimiters in the exported file (not a very good idea!) you may specify a value of 0.

The exporting of comments can be stopped altogether by using the -s option.

Variation lines, to any depth, are exported after the main line move (i.e the main line move appears first, and then any variations appear immediately after). The variation delimiter characters can be changed from the default, by using the -v and -V options, in the same way the comment delimiters can. The default variations delimiters are:

Format	Variation Start	Variation End
ChessBase Format	[	]
PGN	(	)

The exporting of variations can be stopped altogether by using the -S option.

When exporting in ChessBase-format, the evaluation symbols are also written into the ASCII file, but those symbols that are 8-bit are converted to a "representation" (i.e the triangle symbol is converted to the string "<idea>"). Also characters such as umlauts are anglicised, so that names like "K<o:>ningstein" become "Koeningstein". The representation used for the symbols is proprietary, and I hope that someone will devise a compact, readable and portable representation for such symbols someday.

When exporting in PGN-format, the evaluation symbols may be written as Numeric Annotation Glyphs (NAGs), as per the PGN specification, or in the traditional way with '!', '?', etc. The latter method is selected by specifying an output format of "pgn_no_nag" with the -f option. Be warned though that the no-NAG method does not cover all the possible evaluations that may be "attached" to a move from within ChessBase; the others ones are simply thrown away.

The range of games to export can be selected by using the -r option, the argument to this option defining the range of games to export as "first-last". If the "first" number is missing it is taken to mean '1', and if the "last" number is missing it is taken to mean whatever the last game in the database is. For example:

-r 17-32 Export game 17 to 32

-r -20 Export game 1 to 20

-r 5- Export game 5 onwards

The ASCII file is normally truncated to zero length (i.e. overwritten) when exporting games, but if you wish to append some games to an ASCII file use the -a option to open the ASCII file in "append" mode.

Exporting Diagrams

You may export diagrams in two different formats, as well as a user-defined format. Diagram generation is controlled using the "-d" option:

-d cb Exports diagrams in "ChessBase format" (for example (wKe1,Bc1,f1;bKh8,Qe4)")

-d 8x8 Exports an ASCII represention of the chess board with lower-case letters for black pieces and upper-case letters for white pieces.

-d 8x8=file Export an ASCII representation of the chess board but using the characters defined in "file". The user can define the following settings:

• The characters used for white and black pieces on either white or black squares.
• The characters used for the borders and the corners.
• The characters used for empty white and black squares.
• Whether to add spaces between squares (which makes the board more readable directly from the screen, given the aspect ratio of the monitor).
• Whether to generate borders or not.

For specific settings see the file "normal.def" which contains all the possible setting names and information on how to assign the values. Note that if the "file" cannot be found, it will be looked for in the directory in which CBASCII.EXE exists, allowing the definition files to be centralized.

The location of the diagram is controlled by placing the traditional ChessBase diagram marker (Ctrl-D) or the keywords "DIAGRAM" or "DIAGRAMM" at the start of a ChessBase move comment. Once the diagram has been generated the marker or keywords will be skipped and any remaining comments will be exported in the normal way.

Diagrams generated to PGN files are "commented out" using the '%' construct, so that PGN converters can ignore them safely.

Checksum errors

ChessBase games have a checksum value that is used to detect errors in the ChessBase database. CBASCII will validate the checksum when reading the ChessBase database and if it's incorrect will report an error and stop converting that game. If you wish to ignore checksum errors (not a brilliant idea) you may specify the -k option and checksum error reporting will be disabled. One valid use of the -k option is after using the Windows version of the ChessBase ECO utility; this seems to either attempt to "protect" the databases it works on, by applying the informator-type protection to the game headers, or else it is simply broken.

Importing

When converting from ASCII to ChessBase (known as "importing") CBASCII will only read ASCII files stored in PGN-format. This is because PGN is designed for just this purpose, being easily readable by both Humans and Computers alike. Other ASCII file formats are difficult (for a computer) to read, and miss out large chunks of possibly useful data. One of the best things about PGN is the way every possible field of the game header (like the White player name, and the Site name, etc.) is defined and has its own "tag-pair".

When importing from a PGN file, CBASCII will construct the ChessBase game header fields based on the PGN tag-pairs, as defined below:

• The Event tag-pair is the first string in the source field, unless it's contents match that of the Site tag-pair, in which case it is ignored.
• The Site tag-pair is appended to the source field, separated by ", " if the source field contains something already (i.e. the Event tag-pair contents).
• The first number in the Date tag-pair becomes the year.
• The Round tag-pair is appended to the source field, delimited by '(' and ')' characters, and separated by " " if the source field contains something already (i.e. the Site and/or Event tag-pair contents).
• The White tag-pair becomes the first string in the players field.
• The Black tag-pair is appended to the players field, separated by "-" if the players field contains something already (i.e. the White tag-pair contents).
• The ECO tag-pair becomes the ECO code.
• The Annotator tag-pair is appended to the source field, delimited by '[' and ']' characters, and separated by " " if the source field contains something already (i.e. the Site/Event/Round tag-pair contents).
• The WhiteElo and BlackElo tag-pairs become the White and Black Elo values.
• The FEN tag-pair becomes the game partial position, including castling rights, active colour, move number, en-passant files etc.

If any of the above tag-pairs are missing, or they contain "?", the data they would represent is simply not added to the game header; CBASCII is not fussy about the order of the tag-pairs or whether any particular tag-pair exists, though there must be at least one tag-pair so that CBASCII knows when a game starts (this is because CBASCII will ignore any rubbish before the tag-pairs and after the game terminator, so you can, for example, use it to extract games posted to the USENET newsgroups rec.games.chess.* without editing the article first).

Some processing is done on the white and black players names and the annotator name, in order to make it more "ChessBase standard":

1. Any space is removed after a comma.
2. A trailing period at the end of the name is removed if it follows a single-uppercase letter.
3. Any hyphen characters ('-') will be converted to underscores ('_'), as the hyphens are likely to be confused with the White/Black player delimiter.

Example:

[Event "Friendly"]

[Site "Brighton Chess Club"]

[Date "1994.01.19"]

[Round "1"]

[White "Coverwell, R."]

[Black "Duplain, A."]

[Result "1/2-1/2"]

[ECO "D66"]

[Annotator "Duplain, A."]

Becomes:

Players: Coverwell,R-Duplain,A

Source: Friendly, Brighton Chess Club (1) [Duplain,A]

Result: d

Year: 1994

ECO: D66

Move number need not exist before any of the moves in the movetext area, but if they do CBASCII will check that they contain the value it expects.

Any move comments in the PGN file are formatted for use within ChessBase (3 rows of 78 characters) and any comments longer than this are silently ignored. Note that ChessBase-for-Windows onwards now supports long comments so the above formatting could be very annoying. In order to allow long, unformatted comments to converted specify the -l option.

The default comment delimiter characters cannot be changed from the default ('{' and '}') when importing.

Comments can be ignored in the PGN file by using the -s option.

Any variations in the PGN file are added to ChessBase game, but they must exist immediately after the main line move, for example this wouldn't work:

1. e4 e5 (1. c4 Nf6) 2. Nf3 ...

but this would:

1.e4 (1. c4 Nf6) 1... e5 2. Nf3 ...

Variations can be ignored in the PGN file by using the -S option (but even if this option is specified CBASCII will still parse them and check their contents, it just won't add them to the ChessBase game).

The range of games to import can be selected by using the -r option, the argument to this option defining the range of games to import as "first"-"last". If the "first" number is missing it is taken to mean '1', and if the "last" number is missing it is taken to mean whatever the last game in the ASCII file is. For example:

-r 17-32 Import game 17 to 32

-r -20 Import game 1 to 20

-r 5- Import game 5 onwards

CBASCII will still parse and check every game in the ASCII file, but will only add the specified games to the ChessBase database.

If you wish to validate a PGN file, but don't want to add the games to a database you can use the -t option to put CBASCII into "test" mode. Also useful in this regard is the -I flag (capital I); this makes all CBASCII errors non-fatal allowing all the games with errors to be found in one pass; though this doesn't mean that all the errors in these games will be displayed, only the first one.

180-Move Limit

The MS-DOS implementation of ChessBase appears to have a maximum limit of 180-moves that are allowed in any one game. Strangely, the Atari implementation doesn't suffer from this limitation. CBASCII will therefore, by default, truncate games to 180-moves when importing, unless the -E option is used. Also CB-for-Windows also doesn't have this limitation.

PGN compliance

CBASCII is compliant with PGN specification 1994.03.12, with the following exceptions:

• Section 8.1: Tag-pair parsing is pretty much "export format", with one tag-pair per line, and one white space between the symbol token and the string token. No space is allowed between the left brackettoken and the symbol token, and the right bracket token and the string token.
• Section 8.2.2.2: Black move numbers are also inserted at the start of a variation line, and at the termination of a variation line (in the next-higher level), as necessary.
• Section 8.2.3.3: During export, disambiguating file letters and/or rank numbers are added to the notation even if the move is not "legally ambiguous", but is "technically ambiguous". For example if a Knight moved to a square that the other Knight could have moved to, the move would be "technically ambiguous", but if that other Knight could not move as it would expose check to it's King, the move would not be "legally ambiguous". During import though, moves are checked for legality so the disambiguiting information is not necessary.
• Section 8.2.3.6: Parsing of "relaxed" import format SAN is not supported.
• Appendix A: Multiple fields within player-related tag-pairs are not supported.
• All supplemental tag-pairs except the following are ignored: WhiteElo, BlackElo, ECO, SetUp, FEN, and Annotator. Note that the "SetUp" tag-pair is exported when partial positions in the "FEN" tag-pair are exported, but it is ignored during importing.
• Appendix B: Many NAGs are unused for ChessBase move evaluations as there are many more NAGs than ChessBase supports. Therefore the NAG assignments may change when importing and then re-exporting between PGN files with NAGs.

Acknowledgements

CBASCII, and the other ChessBase utilities I am working on, is based on the trailblazing work done by Horst Aurisch in decoding the ChessBase format. This must have been no mean feat, as ChessBase decided, in their infinite wisdom, to encrypt the data as much as possible. Not only was this stupid, but it also means that any work on the game data is slowed as it has to be decrypted before it can be accessed! Also thanks to Anjo Anjewierden for his work on decoding the comment mechanism used in ChessBase games.

Thanks to Steve J. Edwards for his work on the PGN standard.

Bug reports

Please send bug reports, comments, and insults to me:

Andy Duplain,

Trojan Consulting Ltd., Brighton, UK.

Phone: +44 (0)1273 738913

mailto:andy@trojanco.demon.co.uk