~ubuntu-branches/ubuntu/saucy/dds/saucy

Bo Haglund, Bob Richardson

Rev H, 2007-04-23

 

 

Short description of the DLL functions supported in Double Dummy Problem Solver 1.1

 

 

extern "C" __declspec(dllimport) int __stdcall SolveBoard(struct deal, int target,  

    int solutions,  int mode, struct futureTricks *futp);

 

/* Before SolveBoard can be called, a structure of type "futureTricks" must be declared. 

 

SolveBoard returns a status integer, "no fault" means the DLL supplies the trick data in the

"futureTricks" type structure.

Status codes:   

   1=No fault, 

  -1=Unknown fault, 

  -2=No of cards = 0, 

  -3=target > Number of tricks left,                         

  -4=Duplicated cards, 

  -5=target < -1, 

  -7=target >13, 

  -8=solutions < 1, 

  -9=solutions > 3, 

-10=No of cards > 52

-11=Not used

-12=Suit or rank value out of range for deal.currentTrickSuit or deal.currentTrickRank.

  

Structure ”deal” defines all data needed to describe the deal to be analyzed.

struct deal { 

   int trump;   /* I.e. which suit that is trump or if contract is NT, Spades=0, Hearts=1, 

                         Diamonds=2, Clubs=3,  NT=4 */ 

   int first;      /* 0-3, 0=North, 1=East, 2=South, 3=West , Leading hand for the trick.*/ 

    int currentTrickSuit[3];  /* 0-3 for up to 3 cards in the order played */

   int currentTrickRank[3];  /* 2-14 for up to 3 cards */

   unsigned int remainCards[4][4]; /* 1st index hand (0-3), 2nd index suit (0-3), values as bitstring of ranks

                                    bit 0=0, bit 1=0, bit 2=rank 2, ………. bit 14=rank 14, bit 15=0

    for cards remaining after already played cards (cards already 

    played to the current trick are not included in this bitstring).  

    The decimal value for a card then range between 4 (=rank 2) and 

   16384  (Ace=rank 14). */ 

}; 

 

Parameter ”target” is the number of tricks to be won by the side to play, -1 means that the program 

shall find the maximum number. For equivalent  cards only the highest is returned. 

 

Parameter ”solutions” defines how many card solutions that SolveBoard must return:

  target=1-13, solutions=1:  Returns only one of the cards. Its returned score is the same as target when 

                                          target or higher tricks can be won. Otherwise, score –1 is returned if target 

                                          cannot be reached, or score 0 if no tricks can be won. 

  target=-1, solutions=1:  Returns only one of the optimum cards and its score.

  target=0, solutions=1:  Returns only one of the cards legal to play with score set to 0.

  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 –1 if target cannot be reached, or score 0 for all cards 

                                         legal to play if no tricks can be won.

  target –1, solutions=2:  Return all optimum cards with their scores.

  target=0, solutions=2:  Return all cards legal to play with scores set to 0.

  target irrelevant, solutions=3:  Return all cards that can be legally played with their scores in 

                                                  descending  order.

 

Parameter ”mode” 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 mode determines  whether or not the DLL will search to find the score.

  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 –2 for this card, indicating that there are no alternative cards. This mode 

                  is very fast but you don’t 

  mode=1:  Always search to find the score. Even when the hand to play has only one card,  with possible

                 equivalents, to play.

  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.

                  Example:

                  1st call:  SolveBoard(deal, -1, 1, 1, &fut),  deal.first=1, i.e. East leads.

                  2nd call:  SolveBoard(deal, -1, 1, 2, &fut),  deal.first=2, i.e. South leads.

                  3rd call:  SolveBoard(deal, -1, 1, 2, &fut),  deal.first=3, i.e. West leads. 

                  4th call:  SolveBoard(deal, -1, 1, 2, &fut),  deal.first=0, i.e. North leads.   

 

struct futureTricks { /* 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. */ 

  int nodes;     /* Number of searched nodes */

  int cards;         /*  No of alternative cards  */

  int suit[13];         /* 0=Spades, 1=Hearts, 2=Diamonds, 3=Clubs */

  int rank[13];        /* 2-14 for 2 through Ace */ 

  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 ”equals”, the value is the sum of each ”equal”. */

  int score[13];     /* -1 indicates that target was not reached, otherwise target or max number 

                             of tricks */ 

} ; 

 

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.