# Scid vs. PC Programmer's Reference

Authors: Shane G Hudson (16 Jan 2002), Stevenaaus (2015 -)

## Contents

1. Introduction 2. sc_base 3. sc_book 3. sc_epd 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

## 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 MS 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 / sortup / sortdown / 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:

- -colors: whether each player must have the same color in the two games.
- -event, -site, -round, -year, -month, -day, -result, -eco, -moves: whether both games must have the same event, site, etc.
- -comments, -variations: whether games with comments and/or variations should always be kept and never deleted.
- -setfilter: whether to set the filter to contain all the duplicate games found.
- -usefilter: whether to only examine games in the current filter.

#### 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 [script]

Sorts the current database by the criteria, which is a string containing the criteria to use, (optionally executing script before completing sort). 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 sortup|sortdown

Set sorting order (does not perform sort).

#### 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 tournaments [-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:

- -start gameNumber
- -end gameNumber
- -country countryCode
- -minElo eloRating
- -minGames integer
- -maxGames integer
- -minPlayers integer
- -maxPlayers integer
- -size integer (the maximum list length to return).
- -site siteText
- -player playerText

#### 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_epd

TODO - check this section is ok. It has been renamed from sc_book at sometime.

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 Scid, the opcodes are separated by newline characters instead; this makes EPD positions far easier to edit.

Most sc_epd commands take an ID 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 epd has been altered since it was last opened, created or saved.

#### sc_epd available

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

#### sc_epd close epdID

Closes the epd file, without saving it.

#### sc_epd create filename

Creates a new empty epd 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 epd.

#### sc_epd get epdID

Returns the epd file text for the current position.

#### sc_epd moves epdID

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

#### sc_epd name epdID

Returns the filename for the epd.

#### sc_epd next epdID

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

#### sc_epd open filename

Opens an existing epd 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 epd (in the order they are stored in the epd file).

#### sc_epd readonly epdID

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

#### sc_epd set epdID text

Sets the epd file text for the current position.

#### sc_epd size epdID

Returns the number of positions recorded in the epd.

#### sc_epd strip epdID opcode

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

#### sc_epd write epdID

Saves the current epd file, and keeps it open.

## sc_book

Commands: load / close / moves / positions / movesupdate / update

Commands to access polyglot books (.bin / fruit format) TODO

## 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:

- -white, -black, -event, -site: return the White, Black, Event or Site tag instead.
- -duplicate: return the number of the twin of this game, or 0 if it has no twin.
- -fen boolean: whether to display the FEN representation of the current position.
- -hideNextMove boolean: whether to hide the next move.
- -materialValue boolean: whether to print the numeric material value for each side.
- -tb 0|1|2: how much tablebase information to lookup and display: 0 = no TB output, 1 = score only, 2 = score and best moves.

#### 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 [coord | nonums]

Returns a string or list of the moves reaching the current game position.
Optional arguments: "coord" for coordinate/UCI notation
"nonums" for standard algebraic without move numbers
(Default output is standard algebraic with move numbers);

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:

- -format plain|color|html|latex: output format. Default=plain.
- -shortHeader 0|1: whether to print a short, 3-line verison of the PGN header. Default=0.
- -space 0|1: whether to print a space after move numbers. Default=0.
- -tags 0|1: whether to print non-standard tags. Default=1.
- -comments 0|1: whether to print comments. Default=1.
- -variations 0|1: whether to print variations. Default=1.
- -indentComments 0|1: whether to indent comments. Default=0.
- -indentVars 0|1: whether to indent variationss. Default=0.
- -width integer: line width for word wrapping. Default=99999, a huge value to let a Tcl/Tk text widget do its own wrapping.
- -gameNumber integer: game number to print instead of the current game.

#### 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:

- clipbase: the maximum number of games in the clipbase.
- elo: the highest permitted rating value.
- epd: the maximum number of open EPD files.
- events: the maximum number of unique Events in a database.
- games: the maximum number of games in a database.
- nags: the maximum number of NAGs (annotation symbols) for any single move.
- players: the maximum number of unique Players in a database.
- rounds: the maximum number of unique Rounds in a database.
- sites: the maximum number of unique Sites in a database.
- year: the maximum permitted year of a game date.

#### 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 / moves / movesUCI / location

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_pos moves text

Returns the games movelist in SAN.

#### sc_pos movesUCI text

Returns the games movelist in UCI / alegraic notation.

#### sc_pos location text

Returns the current game 'ply'.

## 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:

- 0: AND -- only search in the current filter, resricting it.
- 1: OR -- search games not in ther filter, adding to the filter.
- 2: RESET -- ignore the filter, resetting it before 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:

- -wq|-bq|-wr|-br|-wn|-bn|-wm|-bm|-wp|-bp two-integer-list
  which specifies the minimum and maximum values of a particular piece type and color; note that wm and bm denote the counts of white or black minor pieces. All the piece types default to a minimum and maximum of zero, except the minor piece (wm and bm) counts which default to a minumum of 0 and maximum of 9.
- -flip boolean
  which specifies whether to ignore colors. The default is false.
- -filter 0|AND|and|1|OR|or|2|IGNORE|ignore
  which specifies the operation on the current filter. The parameter can be a an integer value 0, 1 or 2, or the word AND, OR or IGNORE, or any case-insensitive prefix of any of these words.
- -range two-integer-list
  for the smallest and largest whole move number where each game should be searched.
- -length length
  which specifies the number of successive half-moves the search should match for, an integer value. The default is 1.
- -bishops either|same|opposite
  which specifies, when both sides have one bishop, whether they should be of the same, opposite, or either square color. The default is either.
- -pattern four-element-list:flag,piece,file,rank
  which adds a search pattern. The flag is a boolean, piece is a piece like wp, bk, etc, or ? for any, file is a chessboard file or ?, and rank is a chessboard rank or ?.

## 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.

Last updated 3 April 2018