Scid vs. PC Programmer's Reference

Author: Shane G Hudson, 16-Jan-2002
Last updated by Stevenaaus, 14-Mar-2013

Contents

1. Introduction
2. sc_base
3. sc_book
4. sc_clipbase
5. sc_compact
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

Introduction

Scid vs. PC is a free chess database written in C++ and Tcl/Tk. Two versions of the database interface exist.

  • The full version, Tkscid, incorporates Tcl and Tk and is used in conjunction with Scid's graphical user interface.
  • Tcscid uses Tcl alone and has no GUI. It is useful for writing small scripts that manipulate Scid databases.

  • So it is easy to write programs that use Scid databases, provided you know some Tcl (which is a very easy scripting language to learn) and know the extra Scid-specific commands. This document explains these extra commands. The Scid source code also includes a "scripts" directory with several scripting examples.

    The Tcl commands provided by tcscid and tkscid start with the prefix "sc_" (except for a couple of string processing functions), and are implemented, and further documented, in the file src/tkscid.cpp.

    On Windows, things are a little different. The executable tkscid is renamed to scid.exe, and the Tcl/Tk fontend scid is renamed to scid.gui. The Windows equivalent of tcscid is tcscid.exe.


    Commands

    sc_base

    Commands: autoload / close / count / create / current / description / 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 Scid databases.

    Scid can open eight databases and the (permanent, memory only) clipbase occupies slot nine.

    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 [baseNum]

    Closes a database (current base by default). 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 description [text]

    Get, or set, the text describing a base. Maximum length is 107 chars.

    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 Scid 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 Scid. The filename may represent a Scid-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) Scid-format database to the new format used since Scid 3.0. The database should not already be open. Updates the progress bar if applicable.

    sc_book

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

    This group contains commands for handling "book" (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 Scid, the opcodes are separated by newline characters instead; this makes EPD positions far easier to edit.

    Most sc_book commands take a bookID parameter which is the value returned by sc_book create or sc_book open.

    sc_book altered bookID

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

    sc_book 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 Scid can have open at any time.

    sc_book close bookID

    Closes the book file, without saving it.

    sc_book create filename

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

    sc_book deepest bookID

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

    sc_book get bookID

    Returns the book file text for the current position.

    sc_book moves bookID

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

    sc_book name bookID

    Returns the filename for the book.

    sc_book next bookID

    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_book open filename

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

    sc_book prev bookID

    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_book readonly bookID

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

    sc_book set bookID text

    Sets the book file text for the current position.

    sc_book size bookID

    Returns the number of positions recorded in the book.

    sc_book strip bookID opcode

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

    sc_book write bookID

    Saves the current book file, and keeps it open.

    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 Scid-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

    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_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 / merge / 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 merge baseNum gameNum [endPly]

    Merge the specified game into a variation from the current game position. If given, endPly indicates to merge that number of moves only.

    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 Scid 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 Scid 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 Scid-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 Scid-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 Scid. 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 Scid 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 Scid 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 Scid 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 {-option VALUE}

    Searches for header information: names, dates, results, etc. including the given criteria.

    The options can be:

    white, black, event, site, round, date, results, welo, belo, delo, wtitles, btitles, toMove, eco, length, gameNumber, flip, filter, fStdStart, fPromotions, fComments, fVariations, fAnnotations, fDelete, fWhiteOpening, fBlackOpening, fMiddlegame, fEndgame, fNovelty, fPawnStructure, fTactics, fKingside, fQueenside, fBrilliancy, fBlunder, fUser, fCustom1 , fCustom2 , fCustom3 , fCustom4 , fCustom5 , fCustom6 , pgn, ignoreCase

    Where (for eg) "-fDelete 1" signifies the Delete Flag, and "-delo {Low High}" signifies the Elo difference range. Elo args take a 2 item list (-welo {2400 2500}), Eco a 3 item list and date a 4 item list.

    sc_search material {-option VALUE}

    Searches for material and piece patterns. Like sc_search header, it requires a large number of parameters to be ueful, and could use a rewrite of its parameter processing. Simple searches like "sc_search material -wq {2 2}" will find positions where two white queens are the only material present.

    Valid parameters are:

    sc_tree

    Commands: click / positions / search / size / write

    This group contains commands for tree searches.

    sc_tree click line

    Process a click on the tree line number line, selecting that move and adding it to the game.

    sc_tree positions

    Returns the number of cached positions in the tree cache.

    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.