Bo Haglund, Soren Hein, Bob Richardson
Rev AB, 2018-08-20
GitHub releases are available at https://github.com/dds-bridge/dds/releases
Latest DLL issue with this description is available at http://www.bahnhof.se/wb758135/

Description of the DLL functions supported in Double Dummy Solver 2.9.0

Callable functions
The callable functions are all preceded with extern "C" __declspec(dllimport) int __stdcall.  The prototypes are available in dll.h in the “include” directory.  Return codes are given at the end.

Historical note
In addition to the core functions, further layers of interface functions and functionality have been added to DDS over time.  Therefore it is not always consistent whether a pointer or an entire structure is passed to or from DDS.  So please read the documentation carefully.

For the same reason, the function names are not entirely consistent with respect to the input format.  In the future, functions accepting “binary” deals will end on Bin, and those accepting PBN text deals will end on PBN.  At some point existing function names may be changed as well.

Types of functions

Mode	Single	Multiple	
	Bin	PBN	Bin	PBN	
Solve	SolveBoard
	SolveBoardPBN	SolveAllChunksBin
	SolveAllBoards
SolveAllChunks SolveAllChunksPBN	
Calc	CalcDDtable
CalcPar	CalcDDtablePBN
CalcParPBN	CalcAllTables	CalcAllTablesPBN	
Play	AnalysePlayBin	AnalysePlayPBN	AnalyseAllPlaysBin	AnalyseAllPlaysPBN	

There are currently four main families of solvers, and each solver function contains exactly one of these words:

•	Solve: Solve hands for a given leader, strain etc., whether from the opening lead or later.  (Do not use the function names that are struck through.)
•	Calc: Calculate tables for all 5  4 = 20 combinations leaders and strains in one go.
•	Play: Find the optimal results after each card that was actually played on a given hand.
•	Par:  Calculate the par result.  This can also be integrated within a Calc function.

The Bin functions are for deals that are specified in “binary” format, while the PBN functions are for deals that are specified as PBN-like text strings.  The “Single” functions are for solving a single instance, while the “Multiple” functions are for solving several instances in one call.  If you have multiple hands to solve, you will almost surely be better off using a Multiple function and letting DDS figure out the multi-threading for you – see below.

Par family	Uses	Output format	
		Text-1	Text-2	Bin	
Par	Vul, but not dealer	Par	SidesPar	SidesParBin	
Dealer	Vul and dealer	(not available)	DealerPar	DealerParBin	

The Par functions are divided differently, as they operate on a finished Calc table (or in the case of CalcPar and CalcParPBN, the par results are generated directly from a Calc function as well).  Par calculations are so fast that they are never multi-threaded.

The “Par” family, which does not contain the word “Dealer”, makes use of the vulnerability but not of the dealer in a given deal.  This can lead to rare differences depending on who opens the bidding; for example both sides might make 1NT.  The “Dealer” family makes use of both the vulnerability and the dealer to arrive at a single overall par score.

The Text-1 and Text-2 output formats are described later.  The “Bin” output format can be used to generate your own output text strings if you don’t like ours.  The two help functions ConvertToSidesTextFormat and ConvertToDealerTextFormat do this for the Text-2 and Bin formats, respectively, and you can look at the code at the end of Par.cpp if you are so inclined.

There are also some functions to do with DDS itself:
•	GetDDSInfo can provide information about the DLL and how it is compiled and configured.
•	ErrorMessage can turn an error code into an error string.
•	SetThreading controls the type of threading that is used internally.  If you’re using a ready-made DLL, you probably don’t need to call this.
•	SetMaxThreads sets the maximum number of threads to be used internally.
•	SetResources sets both the maximum memory and the maximum number of threads.  This of SetMaxThreads should probably always be called on Linux/Mac, with a zero argument for auto-configuration.
•	FreeMemory relinquishes all dynamically allocated memory.

Multi-threading
DDS is quite optimized for performance including multi-threading.  For example, DDS takes advantage of similarity between hands (such as the same cards and strain but a different declarer) and solves such hands as groups.  DDS sets up threads and tries to load the threads as equally as possible, looking into the individual hands as well.  Unless you have an unusual set-up, you’re probably not going to beat DDS’s multi-threading by trying to do it manually instead.

DDS has two types of threads available internally, “large” ones which are a bit faster and use more memory, and “small” ones which are the opposite.  DDS automatically chooses the right mixture of thread types based on the available memory and number of threads.

Function	Arguments	Format 	Comment	
SolveBoard	struct deal dl,
int target,  
int solutions,  
int mode, 
struct futureTricks *futp, 
int threadIndex	Binary 	The most basic function, solves a single hand from the beginning or from later play	
SolveBoardPBN	struct dealPBN dlPBN,
int target,  
int solutions,  
int mode, 
struct futureTricks *futp, 
int threadIndex	PBN 	As SolveBoard, but with PBN deal format.	
CalcDDtable	struct ddTableDeal 
  tableDeal, 
struct ddTableResults 
  * tablep	Binary 	Solves an initial hand for all possible declarers and denominations (up to 20 combinations)	
CalcDDtablePBN	struct ddTableDealPBN
  tableDealPBN, 
struct ddTableResults 
  * tablep	PBN 
	As CalcDDtable, but with PBN deal format.	
CalcAllTables	struct ddTableDeals 
  * dealsp,
int mode, 
int trumpFilter[5], 
struct ddTablesRes *resp, 
struct allParResults 
  * presp	Binary 	Solves a number of hands in parallel.  Multi-threaded.	
CalcAllTablesPBN	struct ddTableDealsPBN 
  *dealsp, 
int mode, 
int trumpFilter[5], 
struct ddTablesRes *resp, 
struct allParResults 
  * presp	PBN 
	As CalcAllTables, but with PBN deal format.	
SolveAllBoards	struct boardsPBN *bop,
struct solvedBoards 
  * solvedp	PBN 
	Consider using this instead of the next 2 “Chunk” functions”!	
SolveAllChunksBin	struct boards *bop, 
struct solvedBoards 
  *solvedp, 
int chunkSize	Binary 
	Solves a number of hands in parallel. Multi-threaded.	
SolveAllChunks	struct boardsPBN *bop, 
struct solvedBoards 
  * solvedp, 
int chunkSize	PBN	Alias for SolveAllChunksPBN; don’t use!	
SolveAllChunksPBN	struct boardsPBN *bop, 
struct solvedBoards 
  * solvedp, 
int chunkSize	PBN 
	Solves a number of hands in parallel. Multi-threaded.	

Par	struct ddTableResults 
  * tablep, 
struct parResults *presp, 
int vulnerable	No format 
	Solves for the par contracts given a DD result table.  	
DealerPar	struct ddTableResults 
  * tablep, 
struct parResultsDealer 
  * presp, 
int dealer, 
int vulnerable	No format 
	Similar to Par(), but requires and uses knowledge of the dealer.	
DealerParBin	struct ddTableResults 
  * tablep, 
struct parResultsMaster 
  * presp,
int dealer, 
int vulnerable	Binary	Similar to DealerPar, but with binary output.	
ConvertToDealerTextFormat	struct parResultsMaster  
  * pres, 
char *resp	Text	Example of text output from DealerParBin.	
SidesPar	struct ddTableResults 
  *tablep, 
struct parResultsDealer 
  * presp,
int vulnerable 	No format 	Par results are given for sides with the DealerPar output format.	
SidesParBin	struct ddTableResults 
  * tablep, 
struct parResultsMaster     
  sidesRes[2],
int vulnerable	Binary	Similar to SidesPar, but with binary output.	
ConvertToSidesTextFormat	struct parResultsMaster 
  * pres, 
struct parTextResults 
  * resp	Text	Example of text output from SidesParBin.	
CalcPar	struct ddTableDeal 
  tableDeal, 
int vulnerable, 
struct ddTableResults
  * tablep, 
struct parResults * presp	Binary	Solves for both the DD result table and the par contracts. Is deprecated, use a CalcDDtable function plus Par() instead!	
CalcParPBN	struct ddTableDealPBN  
  tableDealPBN, 
struct ddTableResults
  * tablep, 
int vulnerable, 
struct parResults * presp	PBN 	As CalcPar, but with PBN input format. Is deprecated, use a CalcDDtable function plus Par() instead! 	

AnalysePlayBin	struct deal dl, 
struct playTraceBin play,
struct solvedPlay 
  * solvedp, 
int thrId	Binary 
	Returns the par result after each card in a particular play sequence	
AnalysePlayPBN	struct dealPBN dlPBN, 
struct playTracePBN 
  playPBN, 
struct solvedPlay 
  * solvedp, 
int thrId	PBN 
	As AnalysePlayBin, but with PBN deal format.	
AnalyseAllPlaysBin	struct boards *bop, 
struct playTracesBin *plp, 
struct solvedPlays 
  * solvedp, 
int chunkSize	Binary 
	Solves a number of hands with play sequences in parallel.  Multi-threaded.	
AnalyseAllPlaysPBN	struct boardsPBN *bopPBN, 
struct playTracesPBN 
  * plpPBN, 
struct solvedPlays 
  * solvedp, 
int chunkSize	PBN 
	As AnalyseAllPlaysBin, but with PBN deal format.	
SetThreading	int code		Can be used to select the multi-threading system that is used internally.  You probably don’t need this.  The codes are in dll.h	
SetMaxThreads	int userThreads		Used at initial start and can also be called with a request for allocating memory for a specified number of threads.  Is apparently mandatory on Linux and Mac (optional on Windows)	
SetResources	int maxMemoryMB,
int maxThreads		Like SetMaxThreads, but also sets the maximum memory to use.  One of these two functions is enough.	
Fehler! Verweisquelle konnte nicht gefunden werden.	void		Frees all allocated dynamical memory.	
GetDDSInfo	DDSInfo * info			
ErrorMessage	int code,
char line[80]		Turns a return code into an error message string	

Data structures

Common encodings are as follows.

Encoding	Element	Value	
Suit	Spades	
Hearts 	
Diamonds
Clubs 	
NT 		0
1
2
3
4	
Hand	North 	
East 	
South 	
West 		0
1
2
3	
Vulnerable	None
Both
NS only
EW only	0
1
2
3	
Side	N-S
E-W	0
1	
Card 	Bit 2	 
…
Bit 13	 
Bit 14		Rank of deuce

Rank of king
Rank of ace	
Holding	A value of 16388 = 16384 + 4 is the encoding for the holding “A2” (ace and deuce).
The two lowest bits are always zero.	
PBN	Whole hand	Example:
W:T5.K4.652.A98542 K6.QJT976.QT7.Q6 432.A.AKJ93.JT73 AQJ987.8532.84.K	

struct	Field	Comment	
deal	int trump;	Suit encoding	
	int first;	The hand leading to the trick.  Hand encoding
	
	int currentTrickSuit[3];	Up to 3 cards may already have been played to the trick.  Suit encoding. Set to 0 if no card has been played.	
	int currentTrickRank[3];	Up to 3 cards may already have been played to the trick.  Value range 2-14.  Set to 0 if no card has been played.	
	unsigned int remainCards[4][4];	1st index is Hand, 2nd index is Suit.  remainCards uses Holding encoding.	

struct	Field	Comment	
dealPBN	int trump;	Suit encoding	
	int first;	The hand leading to the trick.  Hand encoding	
	int currentTrickSuit[3];	Up to 3 cards may already have been played to the trick.  Suit encoding.	
	int currentTrickRank[3];	Up to 3 cards may already have been played to the trick. Value range 2-14. Set to 0 if no card has been played.	
	char remainCards[80];	Remaining cards.  PBN encoding.	

struct	Field	Comment	
ddTableDeal	unsigned int cards[4][4];	Encodes a deal.  First index is hand.  Hand encoding.  Second index is suit.  Suit encoding.	

struct	Field	Comment	
ddTableDealPBN  	char cards[80];	Encodes a deal.  PBN encoding.	

struct	Field	Comment	
ddTableDeals	int noOfTables;	Number of DD table deals in structure, at most
MAXNOOFTABLES	
	struct ddTableDeal 
  deals[X];	X = MAXNOOFTABLES * DDS_STRAINS	

struct	Field	Comment	
ddTableDealsPBN	int noOfTables;	Number of DD table deals in structure	
	struct ddTableDealPBN
  deals[X];	X = MAXNOOFTABLES * DDS_STRAINS	

struct	Field	Comment	
boards	int noOfBoards;	Number of boards	
	struct deal
  [MAXNOOFBOARDS];		
	int target
  [MAXNOOFBOARDS];	See SolveBoard	
	int solutions
  [MAXNOOFBOARDS];	See SolveBoard	
	int mode
  [MAXNOOFBOARDS];	See SolveBoard	

struct	Field	Comment	
boardsPBN	int noOfBoards;	Number of boards	
	struct dealPBN
  [MAXNOOFBOARDS];		
	int target
  [MAXNOOFBOARDS];	See SolveBoard	
	int solutions
  [MAXNOOFBOARDS];	See SolveBoard	
	int mode
  [MAXNOOFBOARDS];	See SolveBoard	
struct	Field	Comment	
futureTricks	int nodes;	Number of nodes searched by the DD solver	
	int cards;	Number of cards for which a result is returned.  May be all the cards, but equivalent ranks are omitted, so for a holding of KQ76 only the cards K and 7 would be returned, and the “equals” field below would be 2048 (Q) for the king and 64 (6) for the 7.
For KQ765: rank[0] = 13, rank[1] = 7, equals[0] = 4096 (for the Q), equals[1] = 96 (for the 6 and 5).	
	int suit[13];	Suit of the each returned card.  Suit encoding	
	int rank[13];	Rank of the returned card. Value range 2-14.	
	int equals[13];	Lower-ranked equals.  Holding encoding.	
	int score[13];	-1: target not reached.
-2 (if mode == 0):  Only one card to be played; see SolveBoard() description.
Otherwise: Target of maximum number of tricks.	

struct	Field	Comment	
solvedBoards	int noOfBoards;		
	struct futureTricks 
  solvedBoard 
  [MAXNOOFBOARDS];		

Struct	Field	Comment	
ddTableResults	int resTable[5][4];	Encodes the solution of a deal for combinations of denomination and declarer.  First index is denomination. Suit encoding.  Second index is declarer.  Hand encoding.  Each entry is a number of tricks.	

Struct	Field	Comment	
ddTablesRes	int noOfBoards;	Number of DD table deals in structure, at most
  MAXNOOFTABLES	
	struct ddTableResults 
  results[X];	X = MAXNOOFTABLES * DDS_STRAINS	

struct	Field	Comment	
parResults	char parScore[2][16];	First index is NS/EW.  Side encoding.	
	char parContractsString
  [2][128];	First index is NS/EW.  Side encoding.	

struct	Field	Comment	
allParResults	struct parResults
  [MAXNOOFTABLES];	There are up to 20 declarer/strain combinations per DD table	

struct	Field	Comment	
parResultsDealer	int number;		
	int score;		
	char contracts[10][10];		

struct	Field	Comment	
parResultsMaster	int score;		
	int number;		
	struct contractType 
  contracts[10];		

struct	Field	Comment	
contractType	int underTricks;		
	int overTricks;		
	int level;		
	int denom;		
	int seats;		

struct	Field	Comment	
parTextResults	char parText[2][128];		
	int equal;		

struct	Field	Comment	
DDSInfo	int major, minor patch;		
	char versionString[10];	Printable version string	
	int system;	0 unknown, 1 Windows, 2 Cygwin, 3 Linux, 4 Apple	
	int compiler;	0 unknown, 1 Microsoft Visual C++, 2 mingw, 3 GNU g++, 4 clang	
	int constructor;	0 none, 1 DLLMain, 2 Unix-style	
	int threading;	0 none, 1 Windows, 2 OpenMP, 3 GCD	
	int noOfThreads;		
	char systemString[512];	Printable summary string	

struct	Field	Comment	
playTraceBin	int number;	Number of cards in the play trace, starting from the first card in the trace (so excluding any cards in deal in
currentTrickSuit and currentTrickRank)	
	int suit[52];	Suit encoding.	
	int rank[52];	Encoding 2 .. 14 (not Card encoding).	

struct	Field	Comment	
playTracePBN	int number;	Number of cards in the play trace, starting as in playTraceBin	
	char cards[106];	String of cards with no space in between, also not between tricks.  Each card consists of a suit (C/D/H/S) and then a rank (2 .. A).  The string must be null-terminated.	

struct	Field	Comment	
playTracesBin	int noOfBoards;		
	struct playTraceBin 
  plays[MAXNOOFBOARDS];		

struct	Field	Comment	
playTracesPBN	int noOfBoards;		
	Struct playTracePBN 
  plays[MAXNOOFBOARDS];		

struct	Field	Comment	
solvedPlay	int number;		
	int tricks[53];	Starting position and up to 52 cards	

struct	Field	Comment	
solvedPlays	int noOfBoards;		
	struct solvedPlay 
  solved[MAXNOOFBOARDS];		

Functions

SolveBoard
struct deal dl,
int target,  
int solutions,  
int mode, 
struct futureTricks *futp, 
int threadIndex
	SolveBoardPBN
struct dealPBN dl, 
int target,  
int solutions,  
int mode, 
struct futureTricks *futp, 
int threadIndex
	
SolveBoardPBN is just like SolveBoard, except for the input format.  Historically it was one of the first functions, and it exposes the thread index directly to the user.  Later functions generally don’t do that, and they also hide the implementation details such as transposition tables, see below.

SolveBoard solves a single deal “dl” and returns the result in “*futp” which must be declared before calling SolveBoard.

If you have multiple hands to solve, it is always better to group them together into a single function call than to use SolveBoard.

SolveBoard is thread-safe, so several threads can call SolveBoard in parallel. Thus the user of DDS can create threads and call SolveBoard in parallel over them. The maximum number of threads is fixed in the DLL at compile time and is currently 16.  So “threadIndex” must be between 0 and 15 inclusive; see also the function SetMaxThreads.  Together with the PlayAnalyse functions, this is the only function that exposes the thread number to the user.

There is a “transposition table” memory associated with each thread.  Each node in the table is effectively a position after certain cards have been played and other certain cards remain.  The table is not deleted automatically after each call to SolveBoard, so it can be reused from call to call.  However, it only really makes sense to reuse the table when the hand is very similar in the two calls.  The function will still run if this is not the case, but it won’t be as efficient.  The reuse of the transposition table can be controlled by the “mode” parameter, but normally this is not needed and should not be done.

The three parameters “target”, “solutions” and “mode” together control the function.  Generally speaking, the target is the number of tricks to be won (at least) by the side to play; solutions controls how many solutions should be returned; and mode controls the search behavior.  See next page for definitions.

For equivalent cards, only the highest is returned, and lower equivalent cards are encoded in the futureTricks structure (see “equals”).

target	solutions	Comment	
-1	1	Find the maximum number of tricks for the side to play.  
Return only one of the optimum cards and its score.	
-1	2	Find the maximum number of tricks for the side to play.  
Return all optimum cards and their scores.	
0	1	Return only one of the cards legal to play, with score set to 0.	
0	2	Return all cards that legal to play, with score set to 0.	
1 .. 13	1	If score is -1: Target cannot be reached.
If score is 0:  In fact no tricks at all can be won.
If score is > 0:  score will always equal target, even if more tricks can be won.
One of the cards achieving the target is returned.	
1 .. 13	2	Return all cards meeting (at least) the target.  
If the target cannot be achieved, only one card is returned with the score set as above.	
any	3	Return all cards that can be legally played, with their scores in descending order.	

mode	Reuse TT?	Comment	
0	Automatic if same trump suit and the same or nearly the same cards distribution, deal.first
can be different. 	Do not search to find the score if the hand to play has only one card, including its equivalents, to play. Score is set to –2 for this card, indicating that there are no alternative cards. If there are multiple choices for cards to play, search is done to find the score. This mode is very fast but you don’t always search to find the score.	
1		Always search to find the score. Even when the hand to play has only one card, with possible equivalents, to play.  	
2	Always		

Note:  mode no longer always has this effect internally in DDS.  We think mode is no longer useful, and we may use it for something else in the future.  If you think you need it, let us know!

“Reuse” means “reuse the transposition table from the previous run with the same thread number”.  For mode = 2 it is the responsibility of the programmer using the DLL to ensure that reusing the table is safe in the actual situation. Example: Deal is the same, except for deal.first. The trump suit is the same. 

1st call, East leads:  	SolveBoard(deal, -1, 1, 1, &fut, 0), deal.first=1
 	2nd call, South leads:  	SolveBoard(deal, -1, 1, 2, &fut, 0), deal.first=2
 	3rd call, West leads:  	SolveBoard(deal, -1, 1, 2, &fut, 0), deal.first=3
4th call, North leads:  	SolveBoard(deal, -1, 1, 2, &fut, 0), deal.first=0

CalcDDtable
struct ddTableDeal tableDeal, 
struct ddTableResults * tablep	CalcDDtablePBN
struct ddTableDealPBN tableDealPBN, 
struct ddTableResults * tablep	

CalcDDtablePBN is just like CalcDDtable, except for the input format.

CalcDDtable solves a single deal “tableDeal” and returns the double-dummy values for the initial 52 cards for all the 20 combinations of denomination and declarer in “*tablep”, which must be declared before calling CalcDDtable.

CalcAllTables
struct ddTableDeals *dealsp,
int mode, 
int trumpFilter[5], 
struct ddTablesRes *resp, 
struct allParResults *presp

	CalcAllTablesPBN
struct ddTableDealsPBN *dealsp, 
int mode, 
int trumpFilter[5], 
struct ddTablesRes *resp, 
struct allParResults *presp	
CalcAllTablesPBN is just like CalcAllTables, except for the input format.

CalcAllTables calculates the double dummy values of the denomination/declarer hand combinations in “*dealsp” for a number of DD tables in parallel. This increases the speed compared to calculating these values using a CalcDDtable call for each DD table.  The results are returned in “*resp” which must be defined before CalcAllTables is called.

The “mode” parameter contains the vulnerability (Vulnerable encoding; not to be confused with the SolveBoard mode) for use in the par calculation.  It is set to -1 if no par calculation is to be performed.

There are 5 possible denominations or strains (the four trump suits and no trump).   The parameter “trumpFilter” describes which, if any, of the 5 possibilities that will be excluded from the calculations. They are defined in Suit encoding order, so setting trumpFilter to {FALSE, FALSE, TRUE, TRUE, TRUE} means that values will only be calculated for the trump suits spades and hearts. 

The maximum number of DD tables in a CalcAllTables call depends on the number of strains required, see the following table:

Number of strains	Maximum number of DD tables	
5	32	
4	40	
3	53	
2	80	
1	160	

SolveAllBoards
struct boards *bop, 
struct solvedBoards 
  * solvedp	SolveAllChunksBin
struct boards *bop, 
struct solvedBoards *solvedp, 
int chunkSize	SolveAllChunksPBN
struct boardsPBN *bop, 
struct solvedBoards *solvedp, 
int chunkSize

SolveAllChunks is an alias for SolveAllChunksPBN; don’t use it.

SolveAllBoards used to be an alias for SolveAllChunksPBN with a chunkSize of 1; however this has been changed in v2.8, and as of v2.8.4 it is in fact the other way round.  Now SolveAllChunksBin* are aliases to SolveAllBoards, and they ignore the chunk size.  Use SolveAllBoards directly instead!

The SolveAll* functions invoke SolveBoard several times in parallel in multiple threads, rather than sequentially in a single thread.  This increases execution speed.  Up to 200 boards are permitted per call.

For historical reasons, an explanation of chunk size follows.   If the chunk size was 1, then each of the threads started out with a single board.  If there were four threads, then boards 0, 1, 2 and 3 were initially solved.  If thread 2 was finished first, it got the next available board, in this case board 4.  Perhaps this was a particularly easy board, so thread 2 also finished this board before any other thread completed.  Thread 2 then also got board 5, and so on.  This continued until all boards had been solved.  In the end, three of the threads would be waiting for the last thread to finish.

The transposition table in a given thread (see SolveBoard) is generally not reused between board 2, 4 and 5 in thread 2.  This only happens if SolveBoard itself determines that the boards are suspiciously similar.

If the chunk size was 2, then initially thread 0 got boards 0 and 1, thread 1 got boards 2 and 3, thread 2 got boards 4 and 5, and thread 3 got boards 6 and 7.  When a thread was finished, it got two new boards in one go, for instance boards 8 and 9.  The transposition table in a given thread was reused within a chunk.

No matter what the chunk size was, the boards were solved in parallel.  If the user knew that boards are grouped in chunks of 2 or 10, it was possible to force the DD solver to use this knowledge.  However, this is rather limiting on the user, as the alignment must remain perfect throughout the batch.

SolveAllBoards now detects repetitions automatically within a batch, whether or not the hands are evenly arranged and whether or not the duplicates are next to each other.  This is more flexible and transparent to the user, and the overhead is negligible.  Therefore, use SolveAllBoards!

Par
struct ddTableResults *tablep, 
struct parResults *presp, 
int vulnerable	DealerPar
struct ddTableResults *tablep, 
struct parResultsDealer *presp, 
int dealer, 
int vulnerable
	
SidesPar
struct ddTableResults *tablep, 
struct parResultsDealer *sidesRes[2], 
int vulnerable

DealerParBin
struct ddTableResults *tablep, 
struct parResultsMaster * presp, 
int vulnerable	SidesParBin
struct ddTableResults *tablep, 
struct parResultsMaster * presp, 
int dealer, 
int vulnerable
	
ConvertToDealerTextFormat
struct parResultsMaster *pres, 
char *resp	ConvertToSidesTextFormat
struct parResultsMaster *pres,
struct parTextResults *resp	

The functions Par, DealerPar, SidesPar, DealerParBin and SidesParBin calculate the par score and par contracts of a given double-dummy solution matrix “*tablep” which would often be the solution of a call to CalcDDtable.  Since the input is a table, there is no PBN and non-PBN version of these functions.

Before the functions can be called, a structure of the type “parResults”, “parResultsDealer” or “parResultsMaster” must already have been defined.

The “vulnerable” parameter is given using Vulnerable encoding.

The Par() function uses knowledge of the vulnerability, but not of the dealer.  It attempts to return results for both declaring sides.  These results can be different in some rare cases, for instance when both sides can make 1NT due to the opening lead.  

The DealerPar() function also uses knowledge of the “dealer” using Hand encoding.  The argument is that in all practical cases, the dealer is known when the vulnerability is known.  Therefore all results returned will be for the same side.

The SidesPar() function is similar to the Par() function, the only difference is that the par results are given in the same format as for DealerPar().

In Par() and SidesPar() there may be more than one par score; in DealerPar() that is not the case.  Par() returns the scores as a text string, for instance “NS -460”, while DealerPar() and SidesPar() use an integer, -460.

There may be several par contracts, for instance 3NT just making and 5C just making.  Each par contract is returned as a text string.  The formats are a bit different betweeen the two output format alternatives.

Par() returns the par contracts separated by commas.  Possible different trick levels of par score contracts are enumerated in the contract description, e.g the possible trick levels 3, 4 and 5 in no trump are given as 345N.  Pass is also a possible (though very rare) par contract.  Examples:

•	“NS:NS 23S,NS 23H”.  North and South as declarer make 2 or 3 spades and hearts contracts, 2 spades and 2 hearts with an overtrick.  This is from the NS view, shown by “NS:” meaning that NS made the first bid. Note that this information is actually not enough, as it may be that N and S can make a given contract and that either E or W can bid this same contract (for instance 1NT) before N but not before S.  So in the rare cases where the NS and EW sides are not the same, the results will take some manual inspection.
•	“NS:NS 23S,N 23H”:  Only North makes 3 hearts.
•	“EW:NS 23S,N 23H”:  This time the result is the same when EW open the bidding.  

DealerPar() and SidesPar() give each par contract as a separate text string:

•	“4S*-EW-1” means that E and W can both sacrifice in four spades doubled, going down one trick.  
•	“3N-EW”  means that E and W can both make exactly 3NT. 
•	“4N-W+1” means that only West can make 4NT +1.  In the last example, 5NT just making can also be considered a par contract, but North-South don’t have a profitable sacrifice against 4NT, so the par contract is shown in this way.  If North-South did indeed have a profitable sacrifice, perhaps 5C*_NS-2, then par contract would have been shown as “5N-W”.  Par() would show “4N-W+1” as “W 45N”.
•	SidesPar() give the par contract text strings as described above for each side.

DealerParBin and SidesParBin are similar to DealerPar and SidesPar, respectively, except that both functions give the output results in binary using the “parResultsMaster” structure.  This simplifies the writing of a conversion program to get an own result output format.  Examples of such programs are ConvertToDealerTextFormat and ConvertToSidesTextFormat.

After DealerParBin or SidesParBin is called, the results in parResultsMaster are used when calling ConvertToDealerTextFormat  resp. ConvertToSidesTextFormat.

Output example from ConvertToDealerTextFormat:
“Par 110: NS 2S  NS 2H”

Output examples from ConvertToSidesTextFormat:
“NS Par 130: NS 2D+2  NS 2C+2” when it does not matter who starts the bidding.
”NS Par -120: W 2NT
EW Par 120: W 1NT+1” when it matters who starts the bidding.

CalcPar
struct ddTableDeal dl
int vulnerable, 
struct ddTableResults * tp, 
struct parResults *presp	CalcParPBN
struct ddTableDealPBN dl, 
struct ddTableResults * tp, 
int vulnerable, 
struct parResults *presp

	
CalcParPBN is just like CalcPar, except for the input format.  

Each of these functions calculates both the double-dummy table solution and the par solution to a given deal.  

Both functions are deprecated. Instead use one of the CalcDDtable functions followed by Par().

AnalysePlayBin
struct deal dl, 
struct playTraceBin play,
struct solvedPlay *solvedp, 
int thrId	AnalysePlayPBN
struct dealPBN dlPBN, 
struct playTracePBN playPBN, 
struct solvedPlay *solvedp, 
int thrId	

AnalysePlayPBN is just like AnalysePlayBin, except for the input format.

The function returns a list of double-dummy values after each specific played card in a hand.  Since the function uses SolveBoard, the same comments apply concerning the thread number “thrId” and the transposition tables.

As an example, let us say the DD result in a given contract is 9 tricks for declarer.  The play consists of the first trick, two cards from the second trick, and then declarer claims.  The lead and declarer’s play to the second trick (he wins the first trick) are sub-optimal.  Then the trace would look like this, assuming each sub-optimal costs 1 trick:

9 10 10 10 10 9 9

The number of tricks are always seen from declarer’s viewpoint (he is the one to the right of the opening leader).  There is one more result in the trace than there are cards played, because there is a DD value before any card is played, and one DD value after each card played.

As of v2.8.3, the functions can be invoked not just from the beginning of a 13-trick hand, but from any position.  Cards in dl.currentTrickSuit and dl.currentTrickRank are respected.

AnalyseAllPlaysBin
struct boards *bop, 
struct playTracesBin *plp, 
struct solvedPlays *solvedp, 
int chunkSize	AnalyseAllPlaysPBN
struct boardsPBN *bopPBN, 
struct playTracesPBN *plpPBN, 
struct solvedPlays *solvedp, 
int chunkSize	

AnalyseAllPlaysPBN is just like AnalyseAllPlaysBin, except for the input format.

The AnalyseAllPlays* functions invoke SolveBoard several times in parallel in multiple threads, rather than sequentially in a single thread.  This increases execution speed.  Up to 20 boards are permitted per call.

Concerning chunkSize, exactly the same remarks apply as with SolveAllChunksBin.

SetMaxThreads 
int userThreads	SetResources
int maxMemoryMB,
int userThreads	SetThreading
int code	

SetMaxThreads and SetResources set the system resources for DDS.  SetThreading can set the threading system that is used internally in DDS; you probably do not need this.  The codes are in DLL.h.

DDS has two thread sizes internally, “large” (about 95-160 MB) and “small” (about 20-30 MB).  The large ones are about 12-14% faster at the moment.  DDS chooses the best mixture given the resources constraints.  More specifically, the memory usage will be limited as follows.

•	maxMemoryMB plus a percentage (this works out statistically).
•	70% of the free memory.
•	No more than 1800 MB if we’re on a 32-bit system.

The number of threads will currently be limited as follows.

•	If compiled single-threaded, or single-threading is selected: 1.
•	If one of the experimental “IMP” codes is used (don’t use!), 1.5 times the number of processor cores.
•	Otherwise the lower of userThreads and 1.5 times the number of processor cores.
•	But fewer threads if there is not enough memory.

It is possible, especially on non-Windows systems, to call SetMaxThreads() actively, even though the user does not want to influence the default values.  In this case, use a 0  as argument.

SetMaxThreads/SetResources can be called multiple times even within the same session.  So it is theoretically possible to change the number of threads dynamically.

FreeMemory
It is possible to ask DDS to give up its dynamically allocated memory by calling FreeMemory.  This could be useful for instance if there is a long pause where DDS is not used within a session.  DDS will free its memory when the DLL detaches from the user program, so there is no need for the user to call this function before detaching.

GetDDSInfo 
DDSInfo * info		

This function returns various system and version information. 
Return codes

Value	Code	Comment	
1	RETURN_NO_FAULT		
-1	RETURN_UNKNOWN_FAULT	Currently happens when fopen() returns an error or when AnalyseAllPlaysBin() gets a different number of boards in its first two arguments.	
-2	RETURN_ZERO_CARDS	SolveBoard(), self-explanatory.	
-3	RETURN_TARGET_TOO_HIGH	SolveBoard(), target is higher than the number of tricks remaining.	
-4	RETURN_DUPLICATE_CARDS	SolveBoard(), self-explanatory.	
-5	RETURN_TARGET_WRONG_LO	SolveBoard(), target is less than -1.	
-7	RETURN_TARGET_WRONG_HI	SolveBoard(), target is higher than 13.	
-8	RETURN_SOLNS_WRONG_LO	SolveBoard(), solutions is less than 1.	
-9	RETURN_SOLNS_WRONG_HI	SolveBoard(), solutions is higher than 3.	
-10	RETURN_TOO_MANY_CARDS	SolveBoard(), self-explanatory.	
-12	RETURN_SUIT_OR_RANK	SolveBoard(), either currentTrickSuit or currentTrickRank have wrong data.	
-13	RETURN_PLAYED_CARD	SolveBoard(), card already played is also a card still remaining to play.	
-14	RETURN_CARD_COUNT	SolveBoard(), wrong number of remaining cards for a hand.	
-15	RETURN_THREAD_INDEX	SolveBoard(), thread number is less than 0 or higher than the maximum permitted.	
-16	RETURN_MODE_WRONG_LO	SolveBoard(), mode is less than 0.	
-17	RETURN_MODE_WRONG_HI	SolveBoard(), mode is greater than 2.	
-18	RETURN_TRUMP_WRONG	SolveBoard(), trump is not one or 0, 1, 2, 3, 4	
-19	RETURN_FIRST_WRONG	SolveBoard(), first is not one or 0, 1, 2	
-98	RETURN_PLAY_FAULT	AnalysePlay*() family of functions. (a) Less than 0 or more than 52 cards supplied.  (b) Invalid suit or rank supplied.  (c) A played card is not held by the right player.	
-99	RETURN_PBN_FAULT	Returned from a number of places if a PBN string is faulty.	
-101	RETURN_TOO_MANY_THREADS	Currently never returned.	
-102	RETURN_THREAD_CREATE	Returned from multi-threading functions.	
-103	RETURN_THREAD_WAIT	Returned from multi-threading functions when something went wrong while waiting for all threads to complete.	
-201	RETURN_NO_SUIT	CalcAllTables*(), returned when the denomination filter vector has no entries	
-202	RETURN_TOO_MANY_TABLES	CalcAllTables*(), returned when too many tables are requested.	
-301	RETURN_CHUNK_SIZE	SolveAllChunks*(), returned when the chunk size is < 1.	

Revision History

Rev A, 2006-02-25.		First issue.

Rev B, 2006-03-20		Updated issue.

Rev C, 2006-03-28	Updated issue. Addition of the SolveBoard parameter ”mode”.

Rev D, 2006-04-05	Updated issue. Usage of target=0 to list all cards that are legal to play.

Rev E, 2006-05-29	Updated issue. New error code –10 for number of cards > 52.

Rev F, 2006-08-09	Updated issue. New mode parameter value = 2. New error code –11 for calling SolveBoard with mode = 2 and forbidden values of other parameters.

Rev F1, 2006-08-14	Clarifications on conditions for returning scores for the different combinations of the values for target and solutions.

Rev F2, 2006-08-26	New error code –12 for wrongly set values of deal.currentTrickSuit and deal.currentTrickRank.

Rev G, 2007-01-04	New DDS release 1.1, otherwise no change compared to isse F2.

Rev H, 2007-04-23	DDS release 1.4, changes for parameter mode=2.

Rev I, 2010-04-10	DDS release 2.0, multi-thread support.

Rev J, 2010-05-29	DDS release 2.1, OpenMP support, reuse of previous DD transposition table results of similar deals.

Rev K, 2010-10-27	Correction of fault in the description:  2nd index in resTable of the structure ddTableResults is declarer hand.

Rev L, 2011-10-14	Added SolveBoardPBN and CalcDDtablePBN.

Rev M, 2012-07-06	Added SolveAllBoards. 

Rev N, 2012-07-16	Max number of threads is 8.

Rev O, 2012-10-21	Max number of threads is configured at initial start-up, but never exceeds 16. 

Rev P, 2013-03-16	Added functions CalcPar and CalcParPBN.

Rev Q, 2014-01-09	Added functions CalcAllTables/CalcAllTablesPBN. 

Rev R, 2014-01-13	Updated functions CalcAllTables/CalcAllTablesPBN.

Rev S, 2014-01-13	Updated functions CalcAllTables/CalcAllTablesPBN.

Rev T, 2014-03-01	Added function SolveAllChunks.

Rev U, 2014-09-15	Added functions DealerPar, SidesPar, AnalysePlayBin, AnalysePlayPBN, AnalyseAllPlaysBin, AnalyseAllPlaysPBN.

Rev V, 2014-10-14	Added functions SetMaxThreads, FreeMemory, DealerParBin, SidesParBin, ConvertToDealerTextFormat, ConvertToSidesTextFormat.

Rev X, 2014-11-16	Extended maximum number of tables when calling CalcAllTables.	

Rev Y, 2016-01-01	Update to v2.8.3.

Rev Z, 2016-03-20	Update to v2.8.4.

Rev AA, 2018-04-01	Update to v2.9.0 beta.

Rev AB, 2018-08-20	Update to v2.9.0.