8.1 ChessDB Programmers Reference

Contents

1. Introduction
2. sc_base
3. sc_clipbase
4. sc_compact
5. sc_epd
6. sc_filter
7. sc_game
8. sc_info
9. sc_move
10. sc_name
11. sc_optable
12. sc_pos
13. sc_progressBar
14. sc_search
15. sc_tree
16. sc_var
17. Extra string commands
18. Feedback

Introduction

ChessDB (http://chessdb.sourceforge.net) is a free chess database written in C++ with a Tcl/Tk interface. Two versions of the Tcl/Tk interface for ChessDB are compiled:

  1. tkchessdb which incorporates Tcl/Tk and is used to provide the graphical user interface.
  2. tcchessdb which incorporates Tcl (without Tk) and is useful for writing small scripts (with no graphical user interface) that manipulate ChessDB databases.

So it is easy to write programs that use ChessDB databases, provided you know some Tcl/Tk (which is a very easy scripting language to learn) and know the extra ChessDB-specific commands that tcchessdb and tkchessdb provide. This document explains those extra commands.

The ChessDB source package includes (in the scripts subdirectory) a number of sample tcchessdb scripts that use the ChessDB commands described in this document. If you want to write a program that uses a ChessDB database in some way, the scripts are an excellent starting point.

All of the new Tcl commands provided by tcchessdb and tkchessdb start with the prefix "sc_", except for a couple of useful string processing functions.

On the C++ side (see the files in the src directory), tkchessdb.cpp is the file that is compiled to produce tkchessdb and tcchessdb (and chessdb.exe on Windows; see below) so it contains all the code that implements the commands explained in this document. It is the interface between Tcl/Tk code and the rest of the ChessDB C++ code. If there is any information you need that this document does not provide, tkchessdb.cpp will probably be the first C++ source file you will want to examine.

ChessDB on Windows

The situation on UNIX/Linux systems is described above. On Windows, things are a little different. The executable tkchessdb is renamed to chessdb.exe, and the Tcl/Tk fontend chessdb is renamed to chessdb.gui. The Windows equivalent of tcchessdb is tcchessdb.exe, which is not compiled by default but there is a Makefile target for it.

sc_base

Commands: autoload / close / count / create / current / duplicates / ecoStats / export / filename / import / inUse / isReadOnly / numGames / open / slot / sort / stats / switch / tournaments / type / upgrade

This group contains commands for opening, closing and doing other actions on ChessDB databases.

ChessDB has (currently) five database slots, each of which can contain one open database. The final slot is reserved for the clipbase, a database that exists in memory only and acts as a clipboard database.

sc_base autoload [gameNumber]

Sets (or gets) the game number to be autoloaded when the current database is opened. A value of 0 indicates that no game should be loaded, and a value larger than the number of games in the database indicates that the last game should be loaded.

sc_base close

Closes the current database. Returns nothing.

sc_base count [free|used|total]

Returns the number of free, used or total (free + used) database slots. The optional parameter defaults to used.

sc_base create myfile [memoryOnly:boolean]

Creates a new empty database, returning its slot number or an error message. The optional parameter memoryOnly defaults to false and indicates the database should exist in memory only.

sc_base current

Returns the current database slot number.

sc_base duplicates [-option value ...]

Finds twin (duplicate) games in the current database and flags them for deletion. Parameters should be in groups of two (an option and value), and every value is a boolean. Returns the number of deleted games, or an error message.

The recognised options that control whether any two games are considered to be twins are:

sc_base ecoStats ecoPrefix

Returns ECO opening code statistics for the given ECO prefix ("A", "B34", etc) about the current database. The return value is a six-element list containing [0] number of games played, [1] number of 1-0 results, [2] number of 1/2-1-2 results, [3] number of 0-1 results, [4] number of * results, and [5] percentage score, for the specified ECO prefix.

sc_base export current|filter PGN|HTML|LaTeX filename [-option value ...]

Exports the all filter games (or just the current game) to a PGN, HTML or LaTeX file. Updates the progress bar if applicable.

Options:
[-append boolean] [-starttext text] [-endtext text] [-comments boolean] [-variations boolean] [-spaces boolean] [-symbols boolean] [-indentComments boolean] [-indentVariations boolean] [-column boolean]

If the append option is true, the file should already exist and the games are appended to it. The starttext and endtext will appear at the start and end of the file. The final three parameters dictate whether comments and variations should be exported, and whether to add a space after each move number.

sc_base filename [slot]

Returns the file name for the specified slot, which defaults to the current database. The name returned for an empty database is "[empty]" or a translation of it, such as "[leer]" for Deutsch. Similarly, "[clipbase]" (or a translation of it) is returned for the clipbase slot.

sc_base import file filename
sc_base import data pgnData

Imports PGN games from the specified file or string of PGN data into the current database. Updates the progress bar if applicable. Returns a message giving the number of game imported and any errors of warnings encountered.

sc_base inUse

Returns a boolean value: 1 if the current database slot is in use, or 0 if it is empty.

sc_base isReadOnly [set]

If the optional parameter "set" is given, this command tries to set the current database to be read-only and returns an error if it is not successful.

Without the optional "set", it returns a boolean value indicating whether the current database is read-only.

sc_base numGames [slot]

Returns the number of games in the database in the specified slot, which defaults to the current database.

sc_base open [-readonly] filename

Tries to open the specified ChessDB database, in read-only mode if the optional -readonly is included. Updates the progress bar if applicable. Returns the database slot number or an error message.

sc_base slot filename

Given a filename, returns the slot number for the database with that filename if it is opened, or 0 if it is not open in ChessDB. The filename may represent a ChessDB-format database or a PGN file.

sc_base sort criteria

Sorts the current database by the criteria, which is a string containing the criteria to use. Updates the progress bar if applicable. Each criterion in the string should be from the following list and separated by commas, dots or spaces.

Sorting criteria are: Date, Year, Event, Site, Round, White, Black, Eco, Result, Length, Rating, Country, Month, Deleted and Marked.

sc_base stats [slot]

Returns a 11-integer lists of statistics about the database in the specified slot, which defaults to the current database. The list is: [0] number of games, [1] number with delete flag on, [2] number with mark flag on, [3] number with comments, [4] number with variations, [5] minimum year, [6] maximum year, [7] mean year, [8] minimum rating, [9] maximum rating, [10] mean rating.

sc_base switch slot

Switches to the specified database slot. The slot can be a number, or "c" for the clipbase.

sc_base tounaments [-option value ...]

Returns a list containing information about selected tournaments in the current database, with each list element being a 13-element sublist with data about one tournament. Options for restricting the tournament list are:

sc_base type slot [type]

Gets or sets the type icon number for the specified database. If the database is memory-only or read-only, and the type is set, the change only be temporary since no file will be altered. The type icons available are in the tcl/basewind.tcl source file.

sc_base upgrade filename

Upgrades an old (2.x) ChessDB-format database to the new format used since ChessDB 3.0. The database should not already be open. Updates the progress bar if applicable.

sc_clipbase

Commands: copy / clear / paste

This group contains commands for using the clipbase database. A program can find the clipbase slot number with the sc_info clipbase command.

sc_clipbase clear

Clears the clipbase so it contains no games.

sc_clipbase copy

Copies the current game, adding it as a new game in the clipbase database.

sc_clipbase paste

Pastes the last game copied to the clipbase, replacing the current game details and moves.

sc_compact

Commands: games / names / stats

This group contains commands for compacting the current database.

sc_compact games

Removes all deleted games and fragmented space from the game file. Updates the progress bar if applicable. Returns an error message if necessary.

sc_compact names

Removes all unused names from the name file. Updates the progress bar if applicable. Returns an error message if necessary.

sc_compact stats games
sc_compact stats names

Returns compaction statistics for the current database.

If the parameter is "games", it returns a 4-integer list: [0] current number of games, [1] current size of game file in bytes, [2] number of games after compaction, [3] size of game file after compaction.

If the parameter is "names", it returns an 8-integer list: the current number of names, and number of unused names, for each name type (player, event, site, and round).

sc_eco

Commands: base / game / read / reset / size / summary / translate

This group contains commands for ECO opening classification.

sc_eco base allGames:boolean extensions:boolean

Reclassifies all games in the current base by ECO code. Updates the progress bar if applicable. Returns a message stating the number of games classified and time taken.

The first boolean parameter inidicates if all games (not only those with no existing ECO code) should be classified. The second boolean parameter indicates if ChessDB-specific ECO extensions (e.g. "B12j" instead of just "B12") should be used.

If the database is read-only, games can still be classified but the results will not be stored to the database file.

sc_eco game [ply]

Finds and returns the deepest ECO code for the curent game. If the optional parameter "ply" is passed, it returns the ply depth of the deepest match instead of the ECO code.

sc_eco read filename

Resets and reads the ECO classification (.eco) file. Returns the number of positions in the file, or an error message.

sc_eco reset

Resets the ECO classification key to contain no positions.

sc_eco size

Returns the number of positions in the ECO classification key.

sc_eco summary ecoPrefix [htext:boolean]

For the current database and given ECO prefix, returns a summary listing positions for the prefix. For example, if ecoPrefix is "A4", a line for each of A40, A41, ..., A49 will be returned.

If the optional htext (defaults to true) is true, the summary is returned in color hypertext format instead of plain text.

sc_eco translate language fromText toText

Sets up a translation for an ECO opening name phrase for the specified language code. For example, sc_eco translate D {Queens Indian} {Damenindisch} will set the phrase Queens Indian in an ECO opening name to be displayed as Damenindisch in Deutsch (German).

sc_epd

Commands: altered / available / close / create / deepest / get / moves / name / next / open / prev / readonly / set / size / strip / write

This group contains commands for handling EPD files. An EPD file contains a number of chess positions, one per line, with extra text for each position in the form of opcodes (such as "bm" for best move and "pv" for principal variation). Each In the EPD file, all opcodes and their values are stored on the same line as the FEN string for the position, with a semicolon separating each opcode. In ChessDB, the opcodes are separated by newline characters instead; this makes EPD positions far easier to edit.

Most sc_epd commands take a epdID parameter which is the value returned by sc_epd create or sc_epd open.

sc_epd altered epdID

Returns a boolean value indicating if the book has been altered since it was last opened, created or saved.

sc_epd available

Returns a boolean value indicating if another book file can currently be opened or created. Use sc_info limit books to find the maximum number of books ChessDB can have open at any time.

sc_epd close epdID

Closes the book file, without saving it.

sc_epd create filename

Creates a new empty book file called filename. Returns its epdID or an error message.

sc_epd deepest epdID

Returns the deepest ply in the current game (main moves only, not variations) that matches a position in the book.

sc_epd get epdID

Returns the book file text for the current position.

sc_epd load epdID from to

Load the EPD position number N:

sc_epd moves epdID

Returns the list of all legal moves (in standard algebraic notation) from the current position that are recorded in this book.

sc_epd name epdID

Returns the filename for the book.

sc_epd next epdID

Clears the current game and sets its start position to be that of the next position found in the book (in the order they are stored in the book file).

sc_epd open filename

Opens an existing book file called filename. Returns its epdID or an error message.

sc_epd prev epdID

Clears the current game and sets its start position to be that of the previous position found in the book (in the order they are stored in the book file).

sc_epd readonly epdID

Returns a boolean value indicating whether this book file is read-only and cannot be edited.

sc_epd set epdID text

Sets the book file text for the current position.

sc_epd size epdID

Returns the number of positions recorded in the book.

sc_epd strip epdID opcode

Strips the specified EPD opcode from all positions in the book.

sc_epd write epdID

Saves the current book file, and keeps it open.

sc_filter

Commands: copy / count / first / freq / last / locate / negate / next / previous / remove / reset / stats / textfind

This group contains commands that manipulate the current database filter.

sc_filter copy from to

Copies all filter games in the database in slot from to the database in slot to. Updates the progress bar if applicable.

sc_filter count [slot]

Returns the number of games in the filter of the database in the specified slot, which defaults to the current database.

sc_filter first

Returns the game number of the first game in the filter, or 0 if the filter is empty.

sc_filter freq date

Given a start date, returns a list of two values: [0] the number of filter games played since the date, and [1] the total number of database games played since the date.

sc_filter last

Returns the game number of the last game in the filter, or 0 if the filter is empty.

sc_filter locate gameNumber

Given a game number, returns the count of filtered games up to and including that game number. Used for jumping to a specified game number in the game list.

sc_filter negate

Negates the filter to include only excluded games.

sc_filter next

Returns the game number of the next game in the filter, or 0 if there is no next filter game.

sc_filter previous

Returns the game number of the previous game in the filter, or 0 if there is no previous filter game.

sc_filter remove gameNumber

Removes the specified game from the filter.

sc_filter reset [slot]

Returns filter of the database in the specified slot, which defaults to the current database, to contain all games.

sc_filter stats
sc_filter stats all
sc_filter stats elo minRating
sc_filter stats year minYear

Returns statistics about the current filter for all filter games (the default), or only the filter games where both players have a rating of at least minRating, or only the filter games played since 1st January of minYear.

sc_filter textfind filterNumber searchText

Returns the filter number of the next filtered game containing searchText in its White, Black, Event or Site fields, starting at the filterNumber'th filtered game.

sc_game

Commands: altered / crosstable / eco / find / firstMoves / flag / getTag / import / info / list / load / moves / new / novelty / number / pgn / pop / push / reloadTags / save / scores / setTags / startBoard / strip / truncate

This group contains commands that act on the current game.

sc_game altered

Returns a boolean value indicating whether the current game has been altered.

sc_game crosstable plain|html|hypertext|filter [name|rating|score] [allplay|swiss|knockout] [(+|-)(colors|countries|ratings|titles|groups)]

Returns the crosstable for the current game, in plain text, HTML, or color hypertext format. The "filter" option produces no returned result but instead it adds all games in the current tournament to the filter.

sc_game eco [ply]

This is equivalent to sc_eco game.

sc_game firstMoves gameNumber numHalfMoves

Returns the first few moves of the specified game as a line of text. A game number of 0 indicates the current game.

sc_game find game-data parameters

Takes 7 parameters (usually obtained from the user bookmarks file) describing a game in the current database, and returns the game number of the best matching game. The parameters are the original game number, White name, Black name, Site, Round, Year, and Result.

sc_game flag flag gameNumber|all|filter [0|1|invert]

Sets (or gets) the specified flag (D=delete, W=White opening, etc) for the specified game, or all games, or all filtered games. The flag can be set on, off or inverted, according to the final parameter. If the final parameter is not specified, the previous parameter should be a game number and the current value (0 or 1) of the specified flag for that game is returned.

sc_game getTag [-last] tagName

Returns the specified tag for the current game. If the optional "-last" is included, the value is for the last game in the database rather than the current game.

Valid tag names are: Event, Site, Date, Year, Month, Day, Round, Result, White: Black, WhiteWlo, BlackElo, WhiteRType, BlackRType, ECO and Extra.

sc_game import pgnText

Imports the specified PGN text, replacing the current game details and moves. Return a message stating any errors or warnings found.

sc_game info option...

Returns the game information text for the current game, as it appears below the chessboard, in color hypertext. Options include:

sc_game list start count format

Returns a portion of the game list according to the current filter. The portion to print is specified by start and count, where start is in the range 1 to the number of filtered games.

The final argument is the format string -- see IndexEntry::PrintGameInfo() in src/index.cpp for details of the format accepted.

sc_game load gameNumber

Loads the specified game from the current database. Returns an error message if not successful.

sc_game moves [options...]

Returns a string or list of the moves reaching the current game position. Optional arguments: "coord" for coordinate notation (1 move per line); "nomoves" for standard algebraic without move numbers (default output is standard algebraic with move numbers); "list" for list format instead of a single string.

This command is primarily used for getting the sequence of moves to send to a chess engine for analysis of the current position.

sc_game new

Clears the current game.

sc_game novelty [-older|-all] [-updatelabel label] [slot]

Finds the first move in the current game (after the deepest position found in the ECO file if it is loaded) that results in a position not found in the specified database (which defaults to the current database). If a novelty move is found, a string indicating the move number and move is returned, such as "11.Qc2". Otherwise, an error message is returned.

The first optional parameter controls whether all games (which is the default) or only games older than the current game should be examined. The second optional parameter pair indicates a Tcl/Tk label widget that should have its text component updated during the novelty search to show progress, e.g. "Trying: 8...Nxd4" then "Trying: 9.Qxd4", etc.

sc_game number

Returns the current game number.

sc_game pgn [-option value ...]

Returns the PGN representation of the current game. The parameters are pairs of "-option value" settings. Valid options are:

sc_game pop

Pops the current game, returning to the previous oe on the stack.

sc_game push

Saves the current game to a stack so it can be restored, and sets up a new empty game.

sc_game reloadTags

Reloads the tags (White, Black, Event, etc) for a game. Useful when a name that may occur in the current game has been edited.

sc_game save gameNumber

Saves the current game, replacing game numbered gameNumber. If gameNumber is 0, a new game is added to the database.

sc_game scores [maxScore]

Returns a Tcl list of the numeric scores of each move, as found in the commment for each move of the game. A score is a number with the format "+digits.digits" or "-digits.digits" found somewhere in the comment of the move, OR the comment of the first variation of the move.

In this way, both ChessDB annotations which have the form
1.e4 {"+0.13: ...."} e5 ...
and those produced by crafty's annotate command which have the form
1.e4 ({7:+0.12} ...) e5 ...
are recognised. The latter form (comments in variations) had the score from the perspective of the side to move in Crafty versions 17 and older, but now have the score always from White's perspective, since version 18.

The list returned should be read in pairs of values: the first is the move (0.0 = start, 0.5 after White's first move, 1.0 after Black's first move, etc) and the second is the value found.

The parameter maxScore (defaults to 10.0) trims all scores to a maximum absolute value, to prevent plotting of extreme values.

sc_game setTags tagValues...

Sets all the tags (White, Black, Event, etc) for the current game. There should be tag value 13 parameters: Event, Site, Date, Round, White, Black, Result, WhiteElo, WhiteRatingType, BlackElo, BlackRatingType, Eco and Extra. The final value is a string of lines in the format:
[TagName "TagValue"]

sc_game startBoard [fen]

If fen is not supplied, a boolean value is returned indicating whether the current game starts with a non-standard position. Otherwise, the moves of the current game are cleared and its starting positition is set to the specified FEN string. An error message is returned if the FEN string is invalid.

sc_game strip [comments|variations]

Strips all comments or annotations from the current game.

sc_game truncate

Truncates the current game at its current position.

sc_info

Commands: asserts / clipbase / decimal / fsize / gzip / html / limit / preMoveCmd / ratings / tb / validDate / version

This group contains commands for general ChessDB information.

sc_info asserts

Returns the number of assertions checked. This will be 0 if the program was compiled without -DASSERTIONS defined.

sc_info clipbase

Returns the slot number of the clipbase.

sc_info decimal [char]

If char is defined, this command sets the decimal point character to char. Otherwise, it returns the current decimal point character.

sc_info fsize filename

Returns the number of elements (games, lines or positions) in the specified file. For a ChessDB-format database or PGN file, the number of games is returned. For an EPD file, the number of positions is returned. For an opening repertoire file, the number of (include and exclude) lines is returned. The file may be GZip-compressed.

For all types except ChessDB-format databases, only the first 64 kilobytes of the file are examined to compute the number of elements, so the value returned is an estimate if the file exceeds this size. An estimate value is returned as a negative value to distinguish it from an exact value, and is suitably rounded to a multiple of 10, 100 or 1000.

sc_info gzip

Returns a boolean value, indicating if the program was compiled with the zlib library for reading GZip format files.

sc_info html [0|1]

Sets or gets the HTML diagram style number. There are currently two styles, 0 (using images in the "bitmaps" directory) and 1 (which uses images in the "bitmaps2" directory).

sc_info limit type

Returns the integer value of a limit that is built in to ChessDB. Valid types are:

sc_info preMoveCmd [command]

Sets (or returns the current value, if command is not supplied) the pre-move command, which is called before every change of the board position. This is useful for checking if the contents of a window editing the comment for each move has changed, for example.

sc_info ratings

Returns a Tcl list of all known rating types, which currently are: Elo, Rating, Rapid, ICCF, USCF, DWZ and BCF.

sc_info tb [directory]

If directory is supplied, this command sets the directory where tablebase files are located to directory, and returns the largest number of pieces and pawns found by the tablebase decoder. Otherwise, it returns a boolean value indicating if the program was compiled with tablebase support.

sc_info validDate dateString

Returns a boolean value indicating if dateString is a valid date or part of one: 2001.12.31 or 2001.?? for example.

sc_info version [date]

Returns the ChessDB version: "2.4" for example. If the option "date" is added, it returns the version date instead: "May 2001" for example.

sc_move

Commands: add / addSan / back / end / forward / pgn / ply / start

This group contains commands related to navigation within the current game and move entry.

sc_move add from to promo

Tries to add the move specified by the squares from and to (which are integers: 0=a1, 1=b1, 2=c1, ..., 62=g8, 63=h8) and the promotion piece promo (2=Queen, 3=Rook, 4=Bishop, 5=Knight). The squares can be specified in either order. Returns an error message if the move could not be added.

sc_move addSan [move ... ]

Takes a sequence of standard algebraic (SAN) chess moves (ONE per parameter) and tries to add them to the current game. Returns an arror message if any move could not be added, or the number of added moves if all were successful.

Move numbers are ignored, so the command "sc_move addSan 1.e4 e5 2.Nf3 Nf6" is fine at the starting position, for example.

sc_move back [count]

Moves back count moves (default: 1 move) in the current game. Never returns an error.

sc_move end

Moves to the final main-line position in the game.

sc_move forward [count]

Moves forward count moves (default: 1 move) in the current game. Never returns an error.

sc_move pgn [offset]

Moves position in the game according to an offset generated when the PGN representation of the game in color hypertext format was produced. This allows any game point in the PGN window of ChessDB to be reached just by clicking the mouse on it.

sc_move ply [ply]

Moves to the specified ply (half-move) number in the main line of the game.

sc_move start

Moves to the starting position in the game.

sc_name

Commands: correct / edit / info / match / ratings / read / spellcheck

This group contains commands for name spell-checking and editing. Most take a "p|e|s|r" parameter to indicate the type of name: Player, Event, Site or Round.

sc_name correct p|e|s|r corrections

Corrects specified names in the database, as given by corrections.

sc_name edit p|e|s|r all|filter|crosstable old new

Edits a name in the name file. This requires writing the index file, since the ID number of the edited name will change. The change can apply to all games, filtered games only, or games in the current tournament only. It is acceptable for the new name to already exist in the database.

sc_name info [-ratings|-htext] player

Returns information about a player: game stats, rating history, etc. If "-ratings" is specified, only ratings information is returned, in a Tcl list. If "-htext" is specified, the information is in hypertext format (as used in the player information window).

sc_name match p|e|s|r prefix maxMatches

Returns a Tcl list of the first maxMatches names in the database that start with prefix. The list should be read in pairs: the first element of each pair is the frequency, the second is the name.

sc_name ratings

Scans the current database for games with unrated players who have Elo rating information in the spellcheck file, and fills in the missing Elo ratings. Returns a two-element list: the number of changed ratings, and the number of changed games.

sc_name read [filename]

Reads a ChessDB spellcheck (.ssp) file into memory, and returns a list of four integers: the number of player, event, site and round names in the file. If there is no filename argument, this command just returns the same list for the current spellcheck data without reading a new file.

sc_name spellcheck [-max integer] [-surnames boolean] [-ambiguous boolean] players|events|sites|rounds

Scans the current database for spelling corrections, and returns them in in a large text string along with an introductory explanation. Up to the specified number of corrections (default=20000) are included.

If the -surnames option is true (it defaults to false), surname-only player corrections (e.g. "Adams" into "Adams, Michael") are also listed where possible. The -ambiguous option defaults to false and specifies whether ambiguous corrections should be returned.

sc_optable

This group contains commands for creating an opening report or theory table.

To be completed...

sc_pos

Commands: addNag / bestSquare / board / clearNags / fen / getComment / getNags / html / isAt / isLegal / isPromotion / matchMoves / moveNumber / pgnBoard / pgnOffset / probe / setComment / side.

This group contains commands related to the current position.

sc_pos addNag nag

Adds a single NAG (numeric annotation glyph) to the current position. The nag can by in many forms: "3", "$3", "!!", etc. See the funtion game_parseNag in src/game.cpp for details.

sc_pos bestSquare sq

Returns an integer indicating the "best" legal move to or from sq. Both sq and the return value have the format 0=a1, 1=b1, ..., 62=g8, 63=h8. If there is no legal move to or from the specified square, -1 is returned.

This is used for "smart" mouse move entry, but the current algorithm for choosing best moves is very primitive and silly moves are frequently suggested.

sc_pos board

Returns a 64-character string containing the current position, in the square order [a1, b1, ..., g8, h8] with white pieces in capitals and a dot for every empty square. For example, the initial position is "RNBQKBNRPPPPPPPP................................pppppppprbnqkbnr".

sc_pos clearNags

Removes all NAGs (annotation symbols) for the current position.

sc_pos fen

Returns the complete FEN representation of the current position including castling, en passent, the half-move clock and the ply count.

sc_pos getComment

Returns the comment for the current position.

sc_pos getNags

Returns the NAGs for the current position, as a space-separated string of symbols or numbers where no symbolic form is known: "!! +- 37" for exmaple.

sc_pos html

Returns the HTML text for a diagram of the current position, assuming it will be used in a file where there is a subdirctory "bitmaps" that contains the piece/square images.

sc_pos isAt start|end|vstart|vend

Returns the boolean value indicating whether the current position is at the start of the game, end of the game, start of a variation, or end of a variation, depending on the specified parameter.

sc_pos isLegal sq1 sq2

Returns a boolean value indicating if the move between the two squares sq1 and sq2 (which are in integer format: 0=a1, 1=b1, ..., 62=g8, 63=h8, and can be in either order) is legal.

sc_pos isPromo sq1 sq2

Takes two squares (in integer format: 0=a1, 1=b1, ..., 62-g8, 63=h8, and can be in either order) and returns true if they represent a pawn promtion move. It does not check that the move is legal.

sc_pos matchMoves prefix [coord:boolean]

Returns a Tcl list of legal moves matching a specified prefix. Note that any occurence of "x", "=", "+", or "#" is removed from the move text of each move, and the castling moves are "OK" and "OQ" for king and queen-side castling respectively, so that no move is a prefix of any other move.

If coord is true (it defaults to false), coordinate-style moves are also printed, such as "g1f3" for "Nxf3".

This command is primarily used for auto-completion of keyboard move entry and displaying all matching moves as a move is entered.

sc_pos moveNum

Returns the current full move number.

sc_pos pgnBoard pgnText

Given text with PGN moves (e.g. 1.e4 e5 2.Nf3 ...), returns a string indicating the resulting board position in 64 characters, in the same format as returned by sc_pos board. This command may be merged into sc_pos board (with the PGN text as an optional parameter) in a future version.

sc_pos pgnOffset [next:boolean]

Returns the PGN offset of the current move (or next move if the optional next is true) in the current game, which is the number of moves printed up to the move in its PGN representation. This is used for highlighting the current and next move in the PGN window.

sc_pos probe [report|optimal|score]

Probes tablebases for information about the current position. The information returned depends on the parameter, For "report", it returns a report of results for each legal move with the moves grouped by result, as seen in the Tablebase window. For "optimal", it returns a list of optimal moves for this position, For "score" (the default), it returns the tablebase result as an integer where 0 is a draw, 1 means the to move mates in 1, -1 means the side to move is checkmated, etc.

sc_pos setComment text

Sets the comment for the current position.

sc_pos side

Returns the side to move: "white" or "black".

sc_progressBar

sc_progressBar [canvas rect width height [timeLabel]]

With no parameters, this command resets the progress bar so none is used, and notes an interruption so if an operation using the progress bar periodically checks for interruption, it will stop without completing its task.

With 4 or 5 parameters, it sets up a progress bar for use by the next command that updates one, given a canvas widget, the tag name rect of a rectangle object in it, the progress bar width and height, and (optionally) a time label text object in the canvas where a time estimate such as "0:08 / 0:13" is to be displayed.

sc_search

Commands: board / header / material / repertoire

This group contains commands for database searches, except for tree searches which are in the sc_tree group.

All the search commands update the progress bar if applicable.

The search commands take a filterOp parameter which specifies how the current filter should affect the search:

sc_search board filterOp E|P|F|M inVars:boolean

Searches for the current board position. E = an exact position search, P = same pawn structure exactly (and same material), F = pawns on same files (and same material), M = same material only. If inVars is true, variations are also searched -- but this can take much longer..

sc_search header parameters...

Searches for header information: names, dates, results, etc. Including the filterOp, there must be 36 parameters. This is very inconvenient, and a rewrite so one can use much simpler commands like sc_search header -white "Kramnik" -ignoreColors true is likely to be done sometime.

The parameters in order are: 1:White, 2:Black, 3:Event, 4:Site, 5:Round, 6:MinDate, 7:MaxDate, 8:WhiteWins, 9:BlackWins, 10:Draws, 11:NoResults, 12:MinWhiteElo, 13:MaxWhiteElo, 14:MinBlackElo, 15:MaxBlackElo, 16:MinEloDifference, 17:MaxEloDifference, 18:MinECO, 19:MaxECO, 20:GamesWithNoECO, 21:IgnoreColors, 22:filterOp, 23:Deleted, 24:NotDeleted, 25:StandardStart, 26:NonStandardStart, 27:Promotions, 28:NoPromotions, 29:Comments, 30:NoComments, 31:Variations, 32:NoVariations, 33:Marked, 34:NotMarked, 35:MinHalfMoves, 36:MaxHalfMoves.

sc_search material parameters...

Searches for material and piece patterns. Like sc_search header, it requires a large number of parameters and could use a rewrite of its parameter processing. It takes 30 parematers, plus more if there are any patterns.

Valid parameters are:

Example: ...

The paremeters in order are: (to be completed).

Each pattern is specified with four extra parameters: Yes|No, then a piece (wk, bq, etc), then the rank (a-h or ?) and finally the rank (1-8 or ?).

sc_search repertoire add include:boolean
sc_search repertoire clear
sc_search repertoire go filterOp

Searches for positions in an opening repertoire. The sc_search repertoire add command adds the current position to the repertoire, as an include or exclude line depending on the value of include. The sc_search repertoire go function does the repertoire search.

sc_tree

Commands: best / click ? / move / positions / recent (under consideration) / search / size / write

This group contains commands for tree searches.

sc_tree best baseNum count results

Finds the 'count' best (highest rated) games with the current position, where the result is "1-0", "0-1", "1/2-12", "*" or "all".

sc_tree click line

Process a click on the tree line number line, selecting that move and adding it to the game. (Does this really exist? It is documented in the API, but I don't see it in the source code.)

sc_tree positions

Returns the number of cached positions in the tree cache.

sc_tree recent

sc_tree recent [baseNum] [count] [results]

Returns the 'count' most recent games with a result of 0, 1, or 1/2

sc_tree search [-sort alpha|eco|frequency|score] [-time time:boolean]

Performs a tree search, finding all games with the current positions and producing statistics about the moves played from this position. Updates the progress bar if applicable.

The default sorting method is by frequency. If the -time option is specified, the boolean value indicates whether to print time information at the end if the tree output.

sc_tree size

Returns the capacity (maximum number of positions) of the tree cache.

sc_tree write

Writes the tree cache file for the current database. Returns the number of positions in the cache, or an error message.

sc_var

Commands: count / create / delete / enter / exit / first / level / list / moveInto / promote

This group contains commands for handling variations.

sc_var count

Returns the number of variations of the current move.

sc_var create

Creates a new variation for the current move. Never returns an error, even if a variation cannot be created (which only happens when already at the end of an empty variation).

sc_var delete varNumber

Deletes variation varNumber of the current move.

sc_var enter varNumber

Enters the variation varNumber of the current move.

sc_var exit

Exits the current variation.

sc_var first varNumber

Moves the variation varNumber of the current move to the be first in the list.

sc_var level

Returns the current variation depth, where 0 indicates the main line of the game.

sc_var list

Returns a Tcl list of the first moves of each variation of the current move. Each variation with no move is represented by an empty string in the list.

sc_var moveInto varNumber

The old name for sc_var enter. It is deprecated and will be removed in a future version.

sc_var promote varNumber

Promotes the specified variation of the current move by swapping it with the current move.

Extra string commands

Commands: strIsPrefix / strPrefixLen

These commands implement a couple of string functions I needed to have that were not available in Tcl, and would have been far slower if written in Tcl instead of C++.

strIsPrefix short long

Returns a boolean value indicating if short is a prefix of long.

strPrefixLen s1 s2

Returns the length of the common prefix of s1 and s2.

Feedback

If you have any suggestions on how this document could be improved, please email the (drkirkby@users.sourceforge.net) with your comments.

If you write a script that uses these commands that you think may be useful to other ChessDB users, please consider sending it to me for inclusion in the ChessDB package.

If you would like to contribute to the tutorial or see anything that should be updated, corrected or improved, please contact David Kirkby. But please note David only speaks English.


Valid HTML 4.01 Valid CSS!
Website administered by Dr. David Kirkby
This page was last modified: September 16, 2007. 10:41:41 am GMT