historical commit dds 2.0.0

DLL-dds_20_i.rtf

@@ -0,0 +1,140 @@
+{\rtf1\ansi\ansicpg1252\uc1 \deff1\deflang1033\deflangfe1053{\fonttbl{\f0\froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\f1\fswiss\fcharset0\fprq2{\*\panose 020b0604020202020204}Arial;}
+{\f16\froman\fcharset238\fprq2 Times New Roman CE;}{\f17\froman\fcharset204\fprq2 Times New Roman Cyr;}{\f19\froman\fcharset161\fprq2 Times New Roman Greek;}{\f20\froman\fcharset162\fprq2 Times New Roman Tur;}
+{\f21\froman\fcharset186\fprq2 Times New Roman Baltic;}{\f22\fswiss\fcharset238\fprq2 Arial CE;}{\f23\fswiss\fcharset204\fprq2 Arial Cyr;}{\f25\fswiss\fcharset161\fprq2 Arial Greek;}{\f26\fswiss\fcharset162\fprq2 Arial Tur;}
+{\f27\fswiss\fcharset186\fprq2 Arial Baltic;}}{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;
+\red0\green128\blue128;\red0\green128\blue0;\red128\green0\blue128;\red128\green0\blue0;\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;}{\stylesheet{\nowidctlpar\adjustright \f1\cgrid \snext0 Normal;}{
+\s1\nowidctlpar\outlinelevel0\adjustright \f1\cgrid \sbasedon0 \snext0 heading 1;}{\s2\keepn\nowidctlpar\outlinelevel1\adjustright \b\f1\fs20\ul\cf1\lang1053\cgrid \sbasedon0 \snext0 heading 2;}{\s3\keepn\nowidctlpar\outlinelevel2\adjustright 
+\b\f1\fs20\cf1\lang1053\cgrid \sbasedon0 \snext0 heading 3;}{\*\cs10 \additive Default Paragraph Font;}{\*\cs15 \additive \b \sbasedon10 Strong;}}{\info{\title Bo Haglund, Bob Richardson}{\author Bo Haglund}{\operator Bo Haglund}
+{\creatim\yr2007\mo4\dy23\hr19\min18}{\revtim\yr2010\mo4\dy24\hr8\min19}{\version29}{\edmins128}{\nofpages3}{\nofwords1128}{\nofchars6430}{\*\company  }{\nofcharsws0}{\vern89}}\margl1417\margr1417\margt1417\margb1417 
+\widowctrl\ftnbj\aenddoc\hyphhotz425\noxlattoyen\expshrtn\noultrlspc\dntblnsbdb\nospaceforul\hyphcaps0\viewkind4\viewscale100 \fet0\sectd \linex0\headery709\footery709\colsx709\sectdefaultcl {\*\pnseclvl1\pnucrm\pnstart1\pnindent720\pnhang{\pntxta .}}
+{\*\pnseclvl2\pnucltr\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl3\pndec\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl4\pnlcltr\pnstart1\pnindent720\pnhang{\pntxta )}}{\*\pnseclvl5\pndec\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}
+{\*\pnseclvl6\pnlcltr\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl7\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl8\pnlcltr\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl9
+\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}\pard\plain \nowidctlpar\adjustright \f1\cgrid {\fs20\lang1053 Bo Haglund, Bob Richardson
+\par Rev I, 2010-04-10
+\par Latest DLL issue with this description is available at http://www.bahnhof.se/wb758135/
+\par 
+\par 
+\par }\pard\plain \s2\keepn\nowidctlpar\outlinelevel1\adjustright \b\f1\fs20\ul\cf1\lang1053\cgrid {Short description of the DLL functions supported in Double Dummy Problem Solver 2.0
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {\fs20\cf1\lang1053 
+\par }\pard\plain \s3\keepn\nowidctlpar\outlinelevel2\adjustright \b\f1\fs20\cf1\lang1053\cgrid {Callable functions
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {\fs20\cf1\lang1053 
+\par extern "C" __declspec(dllimport) int __stdcall SolveBoard(struct deal, int target,  
+\par     int solutions,  int mode, struct futureTricks *futp, int threadIndex);
+\par 
+\par extern "C" __declspec(dllimport) int __stdcall CalcDDtable(struct ddTableDeal tableDeal, struct ddTableResults * tablep);
+\par 
+\par 
+\par }\pard\plain \s3\keepn\nowidctlpar\outlinelevel2\adjustright \b\f1\fs20\cf1\lang1053\cgrid {SolveBoard
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {\fs20\cf1\lang1053 
+\par SolveBoard is thread-safe, so several threads (max 16) can call SolveBoard in parallel.
+\par 
+\par Before SolveBoard can be called, a structure of type "futureTricks" must be declared. 
+\par 
+\par }{\b\fs20\cf1\lang1053 SolveBoard}{\fs20\cf1\lang1053  returns a status integer, "no fault" means the DLL supplies the trick data in the "futureTricks" type structure.\line Status codes:   
+\par    1=No fault, 
+\par   -1=Unknown fault, 
+\par   -2=No of cards = 0, 
+\par   -3=target > Number of tricks left,                         
+\par   -4=Duplicated cards, 
+\par   -5=target < -1, 
+\par   -7=target >13, 
+\par   -8=solutions < 1, 
+\par   -9=solutions > 3, 
+\par -10=No of cards > 52
+\par -11=Not used
+\par -12=Suit or rank value out of range for deal.currentTrickSuit or deal.currentTrickRank.
+\par -13=Card already played in the current trick is also defined as a remaining card to play.
+\par -14=Wrong number of remaining cards for a hand.
+\par -15=threadIndex < 0 or > 15.\line   \line Structure \'94}{\b\fs20\cf1\lang1053 deal}{\fs20\cf1\lang1053 \'94 defines all data needed to describe the deal to be analyzed.
+\par struct deal \{}{\f0\fs20\cf1\lang1053  
+\par }{\fs20\cf1\lang1053    int trump;   /* I.e. which suit that is trump or if contract is NT, Spades=0, Hearts=1, Diamonds=2, Clubs=3,  NT=4 */}{\f0\fs20\cf1\lang1053  
+\par }{\fs20\cf1\lang1053    int first;      /* 0-3, 0=North, 1=East, 2=South, 3=West , Leading hand for the trick.*/}{\f0\fs20\cf1\lang1053  
+\par     }{\fs20\cf1\lang1053 int currentTrickSuit[3];  /* 0-2 for up to 3 cards in the order played */
+\par    int currentTrickRank[3];  /* 2-14 for up to 3 cards */}{\f0\fs20\cf1\lang1053 
+\par }{\fs20\cf1\lang1053    unsigned int remainCards[4][4]; /* 1}{\fs20\cf1\lang1053\super st}{\fs20\cf1\lang1053  index hand (0-3), 2}{\fs20\cf1\lang1053\super nd}{\fs20\cf1\lang1053  in
+dex suit (0-3), values as bitstring of ranks bit 0=0, bit 1=0, bit 2=rank 2, \'85\'85\'85. bit 14=rank 14, bit 15=0}{\f0\fs20\cf1\lang1053  }{\fs20\cf1\lang1053 
+for cards remaining after already played cards (cards already played to the current trick are not included in this bitstring).  \line  The decimal value for a card then range between 4 (=rank 2) and 16384  (Ace=rank 14). */}{\f0\fs20\cf1\lang1053  
+\par }{\fs20\cf1\lang1053 \};}{\f0\fs20\cf1\lang1053  }{\fs20\cf1\lang1053 
+\par 
+\par Parameter \'94}{\b\fs20\cf1\lang1053 target}{\fs20\cf1\lang1053 \'94 is the number of tricks to be won by the side to play, -1 means that the program}{\f0\fs20\cf1\lang1053  }{\fs20\cf1\lang1053 
+shall find the maximum number. For equivalent  cards only the highest is returned. 
+\par \line Parameter \'94}{\b\fs20\cf1\lang1053 solutions}{\fs20\cf1\lang1053 \'94 defines how many card solutions that SolveBoard must return:
+\par   target=1-13, solutions=1:  Returns only one of the cards. Its returned score is the same as target whentarget or higher tricks can be won. Otherwise, score \endash 1 is returned if target cannot be reached, or score 0 if no tricks can be won. \line 
+  target=-1, solutions=1:  Returns only one of the optimum cards and its score.
+\par   }{\fs20\lang1053 target=0, solutions=1:  Returns only one of the cards legal to play with score set to 0.}{\fs20\cf1\lang1053 \line   target 1-13,
+ solutions=2:  Return all cards meeting target. Their returned scores are the same as target when target or higher tricks can be won. Otherwise, only one card is returned with score \endash 
+1 if target cannot be reached, or score 0 for all cards legal to play if no tricks can be won.\line   target \endash 1, solutions=2:  Return all optimum cards with their scores.
+\par   }{\fs20\lang1053 target=0, solutions=2:  Return all cards legal to play with scores set to 0}{\fs20\cf6\lang1053 .}{\fs20\cf1\lang1053 \line   target irrelevant, solutions=3:  Return all cards that can be legally played with 
+their scores in descending  order.
+\par 
+\par Parameter \'94}{\b\fs20\cf1\lang1053 mode}{\fs20\cf1\lang1053 \'94
+ defines the DLL mode of operation. This mode does not affect the DLL if there are multiple choices for cards to play. If there is just one card to play, or multiple cards that are all equivalent, this mo
+de determines  whether or not the DLL will search to find the score.\line   mode=0:  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 \endash 
+2 for this card, indicating that there are no alternative cards. This mode is very fast but you don\rquote t 
+\par   mode=1:  Always }{\fs20 search to find the score. Even when the hand to play has only one card,  with possible equivalents, to play.  For both mode=0 and mode=1: If the preceding SolveBoard call had the same tru
+mp suit and the same or similar deal, except for deal.first, then the transposition table contents is reused from the preceding SolveBoard call. Setting mode=2 is no longer needed, but can still be done for backwards
+\par compatibility.\line   mode=2:  As for mode=1, but the transposition table contents is reused from the preceding SolveBoard call. Deal must be the same, except for deal.first. Trump suit must be the same. Example:
+\par }\pard \fi720\nowidctlpar\adjustright {\fs20 1}{\fs20\super st}{\fs20  call:  SolveBoard(deal, -1, 1, 1, &fut),  deal.first=1, i.e. East leads.
+\par }\pard \nowidctlpar\adjustright {\fs20  \tab 2}{\fs20\super nd}{\fs20  call:  SolveBoard(deal, -1, 1, 2, &fut),  deal.first=2, i.e. South leads.
+\par  \tab 3rd call:  SolveBoard(deal, -1, 1, 2, &fut),  deal.first=3, i.e. West leads. 
+\par }\pard \fi720\nowidctlpar\adjustright {\fs20 4th call:  SolveBoard(deal, -1, 1, 2, &fut),  deal.first=0, i.e. North leads.   }{\fs20\cf1\lang1053 
+\par }\pard \nowidctlpar\adjustright {\fs20\cf1\lang1053 
+\par struct }{\b\fs20\cf1\lang1053 futureTricks}{\fs20\cf1\lang1053  \{ /* The DLL provides the score (number of tricks) that can be won by the card to play defined by its suit and rank. Array of all alternative cards. */}{\f0\fs20\cf1\lang1053  
+\par }{\fs20\cf1\lang1053   int nodes;     /* Number of searched nodes */
+\par   int cards;         /*  No of alternative cards  */}{\f0\fs20\cf1\lang1053 
+\par }{\fs20\cf1\lang1053   int suit[13];         /* 0=Spades, 1=Hearts, 2=Diamonds, 3=Clubs */
+\par   int rank[13];        /* 2-14 for 2 through Ace *}{\b\fs20\cf1\lang1053 / 
+\par   }{\fs20\cf1\lang1053 int equals[13];        /* Bitstring of ranks for equivalent lower rank cards. The decimal value range between 4 (=2) and 8192 (King=rank 13).  When there are several \'94equals\'94, the value is the sum of each \'94equal\'94. *}{
+\b\fs20\cf1\lang1053 /}{\fs20\cf1\lang1053 
+\par   int score[13];     /* -1 indicates that target was not reached, otherwise target or max numbe of tricks */}{\f0\fs20\cf1\lang1053  
+\par }{\fs20\cf1\lang1053 \} ; 
+\par 
+\par Parameter \'94}{\b\fs20\cf1\lang1053 threadIndex}{\fs20\cf1\lang1053 \'94 defines the identity of the thread used when calling SolveBoard.
+\par Maximum 16 threads can call SolveBoard in parallel, threadIndex must be an integer of the range 0..15.}{
+\par }\pard\plain \s3\keepn\nowidctlpar\outlinelevel2\adjustright \b\f1\fs20\cf1\lang1053\cgrid {
+\par 
+\par CalcDDtable
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {\f0\fs20\cf1\lang1053 
+\par }\pard\plain \s1\keepn\nowidctlpar\outlinelevel0\adjustright \f1\cgrid {\fs20\cf1\lang1053 CalcDDtable calculates the double dummy values of the initial 52 cards for all the 20 trump suit/leading hand combinations.   
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {
+\par }\pard\plain \s1\keepn\nowidctlpar\outlinelevel0\adjustright \f1\cgrid {\fs20\cf1\lang1053 Before CalcDDtable can be called, a structure of type " ddTableResults" must be declared.
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {\b\fs20\cf1\lang1053 CalcDDtable}{\fs20\cf1\lang1053  returns a status integer, "no fault" means the DLL supplies the double dummy scores in the "ddTableResults" type structure.\line Status codes:   
+\par    1=No fault,
+\par    Other status codes are errors, with codes equal to SolveBoard status codes.   }{
+\par 
+\par }{\fs20\cf1\lang1053 Structure \'94}{\b\fs20\cf1\lang1053 ddTableDeal}{\fs20\cf1\lang1053 \'94 defines the dealt cards to be analyzed.}{\fs20 
+\par struct ddTableDeal \{
+\par   unsigned int cards[4][4];   /* 1}{\fs20\super st}{\fs20  index is hand, 2}{\fs20\super nd}{\fs20  index is suit, same coding as for deal.remainCards for SolveBoard. */
+\par \};
+\par 
+\par }{\fs20\cf1\lang1053 struct }{\b\fs20\cf1\lang1053 ddTableResults}{\fs20\cf1\lang1053  \{ /* For each combination trump suit / leading hand, the DLL provides the double dummy score. */}{\fs20 
+\par   int resTable[5][4];\tab /* 1}{\fs20\super st}{\fs20  index is trump (0=Spades, 1=Hearts, 2=Diamonds, 3=Clubs, 4=No Trump 2}{\fs20\super nd}{\fs20  index is leading hand, 0=North, 1=East, 2=South, 3=West */
+\par \};
+\par }{
+\par 
+\par 
+\par 
+\par }\pard\plain \s1\keepn\nowidctlpar\outlinelevel0\adjustright \f1\cgrid {\b\fs20\cf1\lang1053 Revision History
+\par }\pard\plain \nowidctlpar\adjustright \f1\cgrid {\fs20\cf1\lang1053 
+\par Rev A, 2006-02-25.\tab \tab First issue.
+\par 
+\par Rev B, 2006-03-20\tab \tab Updated issue.
+\par 
+\par }\pard \fi-2880\li2880\nowidctlpar\adjustright {\fs20\cf1\lang1053 Rev C, 2006-03-28\tab Updated issue. Addition of the SolveBoard parameter \'94mode\'94.
+\par 
+\par Rev D, 2006-04-05\tab Updated issue. Usage of target=0 to list all cards that are legal to play.
+\par 
+\par Rev E, 2006-05-29\tab Updated issue. New error code \endash 10 for number of cards > 52.
+\par 
+\par Rev F, 2006-08-09\tab Updated issue. New mode parameter value = 2. New error code \endash 11 for calling SolveBoard with mode = 2 and forbidden values of other parameters.
+\par }\pard \nowidctlpar\adjustright {\fs20\cf1\lang1053 
+\par }\pard \fi-2880\li2880\nowidctlpar\adjustright {\fs20\cf1\lang1053 Rev F1, 2006-08-14\tab Clarifications on conditions for returning scores for the different combinations of the values for target and solutions.
+\par 
+\par Rev F2, 2006-08-26\tab New error code \endash 12 for wrongly set values of deal.currentTrickSuit and\line deal.currentTrickRank.
+\par 
+\par Rev G, 2007-01-04\tab New DDS release 1.1, otherwise no change compared to isse F2.
+\par 
+\par Rev H, 2007-04-23\tab DDS release 1.4, changes for parameter mode=2.
+\par 
+\par Rev I,  2010-04-10\tab DDS release 2.0, multi-thread support.
+\par }}