ACBLmerge Logo

ACBLmerge

ACBLmerge is a free (open source) program to merge hand records, double dummy results, and electronic scoring info with ACBLscore output, creating an HTML report for websites.

⇓ Download Now

Finally there is a new release! Why did it take so long? new tout
Latest release runs on Mac OS X out of the box.

Overview

The ACBLscore program provided by the American Contract Bridge League (ACBL) is a very old program. It was originally written for DOS, initially in PL/I and converted to Pascal shortly thereafter. It has been minimally ported from DOS to Windows. ACBLscore can generate many text based reports which were originally designed for fixed-width dot matrix printers. The same reports can also be generated in an HTML format. But the HTML generated by ACBLscore is an extremely minimal effort that makes no use of the sophisticated document formatting that HTML allows. Instead, it simply uses the HTML <pre> tag to display the results as plain text. Embarrassingly, the HTML generated by ACBLscore does not even make a minimal effort to comply with the HTML standard though it displays in all major browsers due to the nearly universal tolerance for sloppy HTML.

ACBLmerge is a program that generates a richer report, one that makes much better use of the HTML formatting capabilities. It can present each deal next to the results for each board provided an electronic hand record is available. This capability of merging hands and results lends the program its name. Moreover, the program can display double dummy results and HCP totals for each board in a manner similar to the Dealmaster Pro recap sheets. Law of Total Tricks (LoTT) calculations and par results are also displayed. A cut-and-paste aid makes it easy to copy hands into e-mail or other documents. Version 1.1.0 introduced popup recap sheets for each pair. Version 1.2.0 introduced support for reading Bridgemate, BridgePad, and BridgeScorer electronic score results, i.e. the contract and opening lead. Version 1.3.0 introduced support for team games, significantly faster double dummy analysis, and the ability to include a summary list of winners in the report.

The HTML output format is detailed in the ACBLmerge Report Features document. It is also possible to generate a slight variant of the HTML report customized for the small screen of an iPhone or iPod Touch. Users with those devices are automatically redirected to the customized reported if it is available when accessing the primary report.

Who uses ACBLmerge?

Since the program is open source I don’t track who downloads it and how they use it. Known users include:

Logo for Bridge Results website
Bridge Results Matchpointer Online (Serving D19)
Adventures in Bridge Unit 132 (Kansas State)
Eastlake Bridge Club Amesbury Duplicate Bridge Club
The Common Game Jacksonville School of Bridge
Monterey Bridge Club Dana Harbour Bridge Center
Santa Cruz Unit 550 Charlotte Bridge Association
Emerald Bridge Club Mercercrest Bridge Club
District 9 Regionals Mid-Atlantic Bridge Conference
Balboa Unit 515 Bridge at the Village

In 2009, 2010, and 2011 I used ACBLmerge to post full results for the Pacific Southwest Regional (San Diego) after setting up an arrangement to have all results sent to me at the end of each day. In 2011 I used the program to post full results for the Palm Springs Regional which is now the second largest regional (3900 tables). Bridge Results is the creation of Philippe Lamoise, a fellow San Diego bridge player. The 2012 Pacific Southwest Regional results were posted using Bridge Results as the web based front-end for easy processing by non-technical users. Bridge Results keeps track of players and partnerships and also has social network functionality. Read more about Bridge Results. At the end of 2012, the District 22 board decided to use Bridge Results for all District 22 regionals and since then Ken Monzingo’s assistant, Sergio Mendivil has done all the file uploading to Bridge Results.

If you find ACBLmerge useful, check out the Payoff Matrix and Lead Solver software too.

License, supported platforms, and conformance

ACBLmerge is written in Perl and released under the terms of GNU General Public License GPLv3. To compute the double dummy results it uses Bo Haglund’s free double dummy solver, DDS, also released under the GNU Public License. DDS is a very efficient solver, requiring less than a minute to consider every denomination and seat for a set of 36 hands on a 1.5 GHz Pentium laptop (circa 2004). On a modern quad-core computer the double dummy analysis may take less than 10 seconds. On non-Windows platforms ACBLmerge uses the open source mdbtools package to read Bridgemate, BridgePad, and BridgeScorer files. On Windows and Mac OS X, the LHA format is read using the open source (LGPL) 7-zip program which is bundled with ACBLmerge.

Perl runs on all major operating systems. Double dummy analysis support is provided for Windows and Mac OS X out of the box. On other platforms double dummy analysis requires installing a Linux package or compiling straight C++ code where the latter should be possible on any platform.

ACBLmerge generates clean HTML that validates as HTML 5. The appearance has been verified in Firefox versions 3–35, Internet Explorer versions 7–11, Safari 3.1–8.03, and Google Chrome versions 4-40. All units are font relative which means the output should scale well if user changes the font size, e.g. via Ctrl+ and Ctrl- in Firefox. HTML appearance is controlled using CSS and may be changed by altering the ACBLmergeCommon.css and ACBLmergePairs.css files.

Send feedback and bug reports to software@lajollabridge.com

Version history

For detailed version information see the Changelog.txt file. The following is a summary of the major changes in recent versions. Versions before the 1.0.6 release are not shown with the exception of the original release.

VersionDateMajor Changes
1.3.5  19-Nov-2014 Mac OS X is fully supported out of the box (and uses latest DDS 2.7.0 for double dummy calculations).
1.3.4  07-Nov-2014 Fixed numerous bugs in par calculation. See Changelog for details.
Fixed N-S and E-W flip of asymmetric double dummy results.
Switched to the latest DDS release (2.7.0, 19-Oct-2014).
American Style (-as switch) now also applies to popup recap sheets.
Added board number linking from recap sheet back to main reports.
Added preliminary support for Board-a-Match (BAM) events.
Switched to 7-zip to read compressed masterpoint database on Windows.
Bug fixes and miscellaneous cleanup. See Changelog for details.
All HTML output is now HTML 5.
1.3.3  26-Jul-2012 Fixed LoTT display (regression in 1.3.2 release).
Switched to the latest DDS release (2.2.1, 16-Jul-2012).
1.3.2  23-Jul-2012 Enhanced data mining support for pair games to include board results, contracts, opening lead, deal, double dummy analysis, par contracts, LoTT and extra trick factor (ETF) calculations.
Now use player numbers in ACBLscore report when available instead of requiring the game file to be supplied for functionality that requires player numbers, e.g. masterpoint tooltip.
Added ability to write hands in Bridge Base LIN format (-l, -linurl switches).
Bug fixes. See Changelog for details.
1.3.1  19-Jun-2012 Added basic data mining (-dm switch) support for team games.
Cleaned up and improved user and player documentation.
Bug fixes. See Changelog for details.
1.3.0  24-Mar-2012 Added support for teams games, notably the field strength calculation, face view, and the masterpoint tooltip features.
Added -w option to show a summary list of masterpoint winners.
Extended Bridgemate / BridgePad support from Windows to all platforms.
Significantly faster double dummy analysis on Windows.
Added support for “old” Duplimate format (.bri files)
Added features (-appdir, -cgip, -dm switches) to support better integration with bridgeresults.net website.
Fixed bug in par computation which caused some sacrifices in a lower ranking denomination to be ignored when a sacrifice was found in a higher denomination.
Added -as option for American Style scores, e.g. 4♠ E 5 instead of 4♠ E +1.
Improved sorting of board results when contracts and/or opening leads are available.
1.2.3  22-May-2011 Bug fixes. See Changelog for details.
1.2.2  24-Apr-2011 Bug fixes. See Changelog for details.
1.2.1  25-Mar-2011 Bug fixes. See Changelog for details.
1.2.0  18-Mar-2011 Added ability to include contract and opening lead from Bridgemate and BridgePad electronic scoring equipment. See -b option.
Added -fs option for field strength calculation (average and geometric mean of masterpoint holdings of all players).
Added -mp option to show player masterpoint holdings via tooltip when mouse pointer is held over a player name.
Added -fc option to show player faces (images) via tooltip when mouse pointer is positioned over a player name.
Added reading and writing of double dummy results from/to PBN files in OptimumResultTable section.
Added Bridgify format to Cut-and-Paste aid to help users who are not given a PBN link or have a broken one because the ACBLmerge user forgot to upload the PBN file.
Beta testing by David Kopper of Wichita, KS (Thanks!)
1.1.3  17-Dec-2010 Added :crlf Perl I/O layer for proper handling of files with Windows CR LF line termination when running from Unix. Added -crlf switch to control line termination of output files.
Default to http://lajollabridge.com/Software/ACBLmerge/ACBLmergeReport.htm for “Explanation of Features” help link if -hurl switch is not specified.
Now only strip path from PDF filename if it is a Windows specific style path; otherwise leave alone anything that could be a valid hyperlink.
Added -pbnurl option to link to a PBN file not placed in the same directory as the HTML file on a web server.
1.1.2  16-Apr-2010 Fixed numerous problems with popup recap sheets generated for Howell (one winner) movements by correcting JavaScript code.
1.1.113-Apr-2010 Fixed bugs introduced in version 1.1.0 when multiple CPUs are used to perform double dummy analysis.
1.1.007-Apr-2010 Added popup recap sheets for each pair.
Fixed iPhone/iPod specific HTML output when player numbers are not present in ACBLscore output.
Fixed “Jump directly to board” links which broke in IE 8 due to a Microsoft issue.
Added option to show a table marker (green square) in center of each deal.
Added ability to inject custom HTML in the <head> element and at start and end of the <body> element.
Placed CSS and JavaScript in separate files (previously embedded in Perl code).
1.0.804-May-2009 Added ability to use multiple CPUs / cores for faster double dummy analysis.
Added code to automatically redirect iPhone / iPod users to iPhone / iPod customized HTML output.
1.0.711-Apr-2010 Mostly bug fixes
1.0.607-Apr-2009 Added iPhone / iPod customized HTML output.
1.0.125-Sep-2008 Original release.

Obtaining the software

ACBLmerge.pl can be downloaded as a zip (for Windows) or gzipped tar (for Unix) archive. Older versions which have a green arrow at the right of the version number (above) can be downloaded by clicking on the green arrow.

The current program archive contains the files listed in the table below.

FilenamePurpose
ACBLmerge.plApplication file (PERL script)
ACBLmergeCommon.jsApplication support file (JavaScript)
ACBLmergePairs.jsApplication support file (JavaScript)
ACBLmergeCommon.cssApplication support file (CSS)
ACBLmergePairs.cssApplication support file (CSS)
ddsolver.exeDouble dummy solver (executable)
dds.dllBo Haglund’s double dummy solver (DLL)
7z.exe7-zip archiver (Version 9.2.0, 32-bit executable)
7z.dll7-zip archiver (Version 9.2.0, 32-bit DLL)
mac-os-x (folder)Folder of Mac OS X specific executables (ddsolver, mdb-export, 7z, 7z.so), necessary dynamic link libraries (lib*), and files included for completeness (mdb-schema, mdb-tables, dds.a)
ACBLmergeAbout.htmDocumentation for ACBLmerge user
ACBLmergeLogo.pngDocumentation for ACBLmerge user (support file)
download.pngDocumentation for ACBLmerge user (support file)
ACBLmergeReport.htmDocumentation for bridge players
ACBLmergeReport.pngDocumentation for bridge players (support file)
Changelog.txtDetailed revision history
facejson.plServer side support file for face view feature
ddsolver.cppC++ source code for ddsolver.exe / ddsolver
dll.hC++ header file for compilation of ddsolver.cpp
ACBLgamedump.plAuxiliary Perl program (utility)
ACBLgamedecode.pmAuxiliary Perl package (utility)

The nine files marked in blue are required to use the full functionality of the application. The mac-os-x folder (also in blue) is required for full functionality on Mac OS X. The second group of files is the documentation for running ACBLmerge, i.e. what you are reading now.

The ACBLmergeReport.png and ACBLmergeLogo.png files explain the ACBLmerge reporting features to bridge players. By default the “Explanation of Features” link in each HTML file created ACBLmerge will point to the copy of these files on the La Jolla Unit website. However, if you wish to keep users on your website, place these two files on your website in the same folder, and link to your website’s copy of ACBLmergeReport.htm from each ACBLmerge generated webpage using the -hurl command line option.

Programmers can learn more about the last two files from the ACBLgamedump documentation. These files are not needed to run the current version of ACBLmerge but are closely tied to its future development.

Setting up the software

On Windows you will need to install the no cost open source Perl interpreter. ActiveState has a good Perl distribution which you can download from their web site. Just double click on the installer (.msi) file and choose the default options. Strawberry Perl is a popular alternative. Perl has been included on Apple computers since Max OS X. Some Unix and Linux distributions have Perl pre-installed.

  1. Install Perl

    Skip this step on Mac OS X.

    Important: If you have a 64-bit version of Windows, which is common for Vista and Windows 7, you can install either a 32-bit or 64-bit version of Perl. But if you are planning to incorporate results from the Bridgemate, BridgePad, or BridgeScorer system, choose the 32-bit version of Perl. Read more.

  2. Unzip all the files into whatever folder you please.

    On Windows, C:\Perl, C:\ACBLmerge, or C:\Program Files\ACBLmerge, or your My Documents folder would all be fine. Windows Vista and Windows 7 make it hard to write directly to C:\Program Files so you may not want to use the C:\Program Files\ACBLmerge location.

    Strictly speaking, only the files colored blue in the table above are required. But no harm will come from simply copying all the files in the archive.

    On Mac OS X, you can double click on archive which will normally have been downloaded into your user Downloads folder. This will expand everything into the folder ~/Downloads/ACBLmerge.

  3. If not Windows or Mac OS X: compile ddd.exe or install the dds Linux package if you want to perform double dummy analysis. Then put a copy of the executable in the same directory as ACBLmerge.pl or any directory on the search path. Read more. On Windows or Mac OS X, the ddsolver.exe or ddsolver programs included in the archive will do the double analysis.
  4. If not Windows or Mac OS X: Install the mdbtools package if you want to include results from the Bridgemate, BridgePad, or BridgeScorer electronic scoring systems. The exact method to do this will depend on your operating system. On Ubuntu (Debian) use one of the following commands or use the Synaptic package manager.

    apt-get install mdbtools (if running as root)
    sudo apt-get install mdbtools (if you are allowed to install packages)

    See below for additional information.

ACBLmerge only requires the threads, URI, and Config Perl packages for basic operation. These packages have been part of the standard Perl installation since 5.6.0. The -b, -dm, -fs, and -mp options require additional Perl packages (DBI, DBD::ODBC, JSON::PP, LWP::UserAgent, Archive::Lha) and their dependencies. The Archive::Lha package is only required when not running on Windows or Mac OS X. Many Perl distributions include some of these packages. If a package is not installed, ACBLmerge will try to install it automatically on Windows when needed by invoking the ActiveState Perl Package Manager (PPM). This has only been tested on Window XP. It should work on Vista or Windows 7 if you are running Perl from an Administrator account, given the file permissions set by the ActiveState Perl installer.

On Unix, you must install the packages yourself — if you are running Unix you probably know how to do this. I could probably automate the process for Ubuntu (Debian) but I am not sure how general that would be for *NIX. The following command is an example of how to install a Perl package that is available on the Comprehensive Perl Archive Network (CPAN) if you have the cpan Unix package installed.

cpan -i DBD::ODBC

Unfortunately, it seems that the author of the Archive::Lha package removed it from CPAN in 2012. To avoid reliance on unsupported code, ACBLmerge 1.3.4 and later bundles the 7-zip archiver and uses it on Windows and Mac OS X to read the LHA format. But on non-Windows platforms, ACBLmerge still requires the Archive::Lha package if masterpoint tooltip or field strength calculations are desired. Old package versions can be downloaded from backPAN. The following example starts an interactive cpan session and tells it to search backPAN and install the archive:

cpan
cpan[1]> o conf urllist push http://backpan.perl.org/
cpan[2]> install ISHIGAKI/Archive-Lha-0.06.tar.gz
cpan[2]> exit

Note: if cpan complains about a missing CHECKSUMS file during the installation and asks whether to proceed, go ahead. If all else fails, here are direct links to the latest (0.06) package and the README file.

Running the software for pair games

Results from ACBLscore must be available. To get the most out of the program you should also provide an electronic hand record. The ACBLscore results must be saved in the “traveler format” as a text or HTML file. From within ACBLscore, navigate as follows: Reports (menu) → Recap/Press (menu) → Screen/File (LR) → 8. Press + Recap (traveler format). Alternatively, at the end you can select → 9. Short Press + Recap (traveler format), a slight variant that does not print out the home city for each player and presents the ranks in a more compact form. An example output filename would be 080914A.txt. If there are multiple sections, answer yes to the question, “Include recap for ALL combined sections?” so that pair names and rankings from all sections are included. The output will show the same board results multiple times but that will not affect the ACBLmerge program.

Important: ACBLmerge processes a single ACBLscore event. It is written to handle multiple sections in a single event. But if you have multiple events in a game file, you must export each event separately and run ACBLmerge once per event.

Also if your event has multiple sections but ACBLscore does not present the “Include recap for ALL combined sections?” prompt, then you must export each section separately and process each results file separately. This issue seems to arise for certain (maybe all) STAC games and NAP games. Do not export one section and then try to append the other sections to it; ACBLmerge will not handle that input properly.

ACBLmerge aims to support output from the current version of ACBLscore. There is no specification for the ACBLscore output and thus the reporting format may change at any time. ACBLmerge may handle older ACBLscore output but testing will be limited. In general club owners should frequently update ACBLscore since masterpoint formulas, allowed event formats, and other details are regularly updated. Check for the latest ACBLscore version on the ACBL website.

The hand record information must be in Duplimate (DUP or BRI), Portable Bridge Notation (PBN), or GIB format. If you use Dealmaster Pro to generate the hands, you can save them from Dealmaster Pro in either Duplimate or PBN format. My recommendation is to give the output file the same name but with a different file extension, e.g. 080914A.dup, 080914A.pbn, or 080914A.gib. ACBLmerge can not read Dealmaster Pro PDF files because PDF is a documentation oriented format rather than a data interchange format.

Once you have both files available, start a DOS shell (on Windows) or the shell of your choice (on Unix / Mac). On Windows XP you can start a DOS shell via Start (menu) → Programs → Accessories → Command Prompt; or more simply via Start (menu) → Run, type cmd, and press <enter>. On Windows 7 (and probably Vista), Microsoft has gone to more trouble to hide the “scary” DOS shell and even the Run Box. See this explanation of how to get the Run Box to appear.

From the DOS or Unix shell, switch to the directory containing your input files (cd = “change directory”) and then run Perl to invoke ACBLmerge.pl as in the example below:

cd C:\Documents and Settings\username\My Documents   (typical for XP)
cd C:\Users\username\Documents   (typical for Win7 / Vista)

perl ACBLmerge.pl
perl C:\ACBLmerge\ACBLmerge.pl   (if ACBLmerge.pl is in the C:\ACBLmerge folder)
perl -S ACBLmerge.pl   (finds ACBLmerge.pl if it is on the system path)

Note: in the last example, the -S switch which occurs before ACBLmerge.pl, is a Perl option rather than an ACBLmerge option.

On Mac OS X, start a command line with the Terminal application. If you unzipped the ACBLmerge download in your user Downloads folder, try the following:

cd ~/Downloads/ACBLmerge###   (where ### is the ACBLmerge version)

perl ACBLmerge.pl

Invoking ACBLmerge without any command arguments will display the full list of available command line options (switches). There are quite a few options, separated into basic options and “advanced” options.

Next try something more useful, for example:

perl ACBLmerge.pl -h 080914A.dup -g -p -o -dd -w

This will use the Duplimate file 080914A.dup as the source of the hand records. Since the -r switch is missing, the ACBLscore results file will be assumed to be named 080914A.txt and to exist in the same directory as the 080914A.dup file. The -o switch will set the HTML output to default to 080914A.htm. The -p and -g switches will cause the PBN and GIB output to be generated as 080914A.pbn and 080914A.gib respectively and links will be included in the HTML output to the PBN and GIB files on the expectation that they will be placed on your website in the same location as your HTML output. The -dd switch causes double dummy analysis to be performed. The -w includes a summary list of matchpoint winners near the top of the report. The title of the web page will default to “Sep 14, 2008 Game Result”.

Only the -h switch together with a filename or the -r switch together with a filename is required. However, you will almost always want the -o switch because otherwise the output HTML will be sent to the screen, i.e. STDOUT, instead of a file. Most users will also want the -dd switch because the makeable contracts, LoTT calculation, and par contract can only be generated when double dummy results are available.

If you want to specify the various filenames exactly, you could instead use a command like this one below:

perl ACBLmerge.pl -h 080914A.dup -r 080914A.htm -g Sep14.gib -p Sep14.pbn -o Sep14.htm -dd

Notice that this example uses the HTML output from ACBLscore rather than the text output. When the -r switch is missing or it is supplied without a filename, ACBLmerge automatically converts the hand filename to a .txt extension, e.g. 080914A.dup → 080914A.txt, and looks for that file. Here the -r 080914A.htm is necessary to find the HTML input.

Sometimes you may have a special game such as a Unit game or run multiple sessions or events in the same day. In these cases you may want to set the HTML page title explicitly using the -t switch. For example:

perl ACBLmerge.pl -h 080914A.dup -g -p -o -dd -w -t "Sep 14, 2008 Unit Game"

This overrides the default of "Mmm DD, YYYY Game Result".

If the output HTML filename will have the name as the input file (regardless of case), ACBLmerge will automatically rename the input file, e.g. to 080914A.orig.htm, to prevent the original file from being clobbered; for example in this case where HTML output from ACBLscore is used:

perl ACBLmerge.pl -h 080914A.dup -r 080914A.htm -g -p -o -dd -w

If you have a PDF hand record available, for example from Dealmaster Pro, a link can be added to the PDF file with the -pdf switch. Also, separate HTML tailored for the small screen of an Apple iPhone or iPod touch can be generated using the -iphone switch, with an output filename like 080914A_iPhone.htm. When a web user views a page from an iPhone or iPod touch, the user will automatically be redirected to the iPhone customized webpage if it has been generated. After these options are included the first example becomes:

perl ACBLmerge.pl -h 080914A.dup -g -p -o -dd -w -pdf -iphone

For any switch which requires a filename to perform its function, you can specify a full (or relative) file path, as is typical for a command line based program. But if you do not specify a filename, ACBLmerge will automatically generate one based on the full filename of either the hand file or the ACBLscore results file by changing the file extension. This can save a lot of typing. The following table lists which filename each switch bases its automatic name generation on and the extension it is changed to.

SwitchBase filenameNew extensionUse
-rHand filename.txtInput file
-gHand filename.gibInput or Output file
-pHand filename.pbnInput or Output file
-lHand filename.linOutput file
-pdfHand filename.pdfInput file
-bResults filename.bwsInput file
-oResults filename.htmOutput file
-iphoneResults filename.htmOutput file
-txtResults filename.txtOutput file
-dmResults filename.jsonOutput file
-fcResults filename.ACM/.ACA/.ACE/.ACL*Input file
-fsResults filename.ACM/.ACA/.ACE/.ACL*Input file
-mpResults filename.ACM/.ACA/.ACE/.ACL*Input file

Note that this behavior cascades, i.e. if the -r switch is specified without a filename, then all the filenames automatically generated from the Results filename are effectively generated from the Hand filename.

*The treatment of the ACBLscore game file filename is a bit more complex. ACBLscore game files have a different extension depending on the session: morning (.ACM), afternoon (.ACA), evening (.ACE), and late (.ACL). This is a poor programming practice, but ACBLmerge must deal with it. If your Results filename follows the standard naming convention generated by ACBLscore, e.g. 110214A.txt, ACBLmerge will use the A (or E, M, L) to automatically generate 110214.ACA. If a valid letter is not found, ACBLmerge will exit with an error. Moreover, if the automatically generated game file is not found in the same directory as the Results file, ACBLmerge will also look in C:\ACBLSCOR\GAMEFILE, the ACBLscore’s default installation directory, if running on Windows.

Special case: The -r switch is special. Since a results file is necessary to do anything, ACBLmerge will assume the -r switch even if you do not specify it and in that case expect to derive a result filename based on the filename supplied to the -h switch. Other switches like -p and -g are optional and therefore will not be assumed.

If running on Unix, do not forget that the Unix filesystem is case sensitive. If ACBLmerge is not finding files that you expect it find automatically, check the case of the file extension.

If an electronic hand record is not available but you would still like to take advantage of the other features provided by ACBLmerge, e.g. the list of winners, the pop-up recap sheets, face view (see below), and so forth, you may run ACBLmerge without specifying the -h switch. The report will show “No hand record” where each hand would normally appear. When the -h option is not specified the -r must be specified because the results filename can not be generated automatically. Also, when the -h option is not supplied, the -p and -g options are meaningless and will be ignored.

Uploading ACBLmerge output to your website

Minimally, you need to upload the HTML output to your website. If you have generated the iPhone customized HTML, don’t forget to upload that too. If your hand record input was in PBN or GIB format and/or you generated those formats, or the LIN format, using the -p, -g, or -l switches, upload those files too; otherwise you will have broken PBN and/or GIB links near the top of the HTML report. Finally, you should upload the .txt and .pdf files if you used the -txt or -pdf switches.

It is unnecessary to upload the BRI, DUP, BWS, or ACBLscore game files.

Important: ACBLmerge assumes that you will be uploading all the files in the same folder on your website regardless of where they were on your filesystem when you ran ACBLmerge. By default ACBLmerge strips the file path from the related files before creating the links. For the GIB, PBN, LIN, and TXT (“View original ACBLscore output”) links you can override this behavior with the -giburl, -pbnurl, -linurl and -txturl switches respectively to explicitly supply the URL (relative or absolute) of the corresponding GIB, PBN, LIN or TXT file. For the PDF file you can override this behavior by specifying a URL for the -pdf switch. In this case, ACBLmerge will not check if the PDF file exists; instead it will simply assume the user is going to place it on the website where indicated.

Including Bridgemate, BridgePad, or BridgeScorer electronic scoring results

The Bridgemate, BridgePad, and Bridge Scorer electronic scoring systems capture the contract and optionally the opening lead. The electronic scoring results are stored in a file with the .bws extension, e.g. 080914A.bws. The contract and opening lead information can be included in the ACBLmerge report by specifying the BWS file using the -b switch, for example:
perl ACBLmerge.pl -h 080914A.dup -b -g -p -o -dd -t "Sep 14, 2008 Unit Game"

I have only tested this functionality for Bridgemate devices but other users have reported that it works for BridgePad and BridgeScorer devices. I would appreciate any feedback on ACBLmerge’s behavior with any of these electronic scoring systems. So far as I know, the electronic scoring output format is not documented. However, the file appears to be written in version 3 of the Microsoft JET database format, the internal format used by Microsoft Access 97. If you have Microsoft Access, you can change the .bws file extension to .mdb open it, and poke around. It is straightforward to read the relevant tables using ODBC and the “Microsoft Access Driver(*.mdb)” ODBC driver that ships with XP, Vista, and Windows 7.

The Microsoft JET database format is very old. Microsoft doesn’t want anything to do with it anymore. They would prefer that database applications use their industrial SQL Server database or one of its derivatives such as the Microsoft SQL Server Data Engine (MSDE), which admittedly are vastly superior to JET. Presumably to push developers in that direction, Microsoft didn’t ship a 64-bit version of the JET ODBC driver, i.e. what appears as the “Microsoft Access Driver (*.mdb)” in the ODBC Data Source Administrator. This means that if ACBLmerge is run with a 64-bit version of Perl, it will be unable to read the Bridgemate or BridgePad results. Unfortunately, Microsoft does not make it very clear that the 64-bit drivers are missing. In 64-bit Windows, the 64-bit and 32-bit ODBC connections and drivers are separate, the 64-bit connections being accessible though the standard ODBC control panel and the 32-bit connections being accessible from the 32-bit Windows on Windows (WoW) ODBC control panel (C:\Windows\SysWoW64\odbcad32.exe). But due to a bug detailed in KB 942976, it is easy to be misled into thinking 64-bit support exists for these drivers. ACBLmerge 1.3.4 and later will terminate with an error if the -b switch is used while running under a 64-bit Perl interpreter.

Starting with version 1.3.0, ACBLmerge can read the electronic scoring files on non-Windows platforms using the open source mdbtools package. This package is probably not installed by default on your operating system, so you will have to install it manually. In the worst case, you might have to download the source code and compile it yourself.

Although ODBC has been ported to Unix and the mdbtools package provides a rudimentary ODBC driver, this approach adds more complications than are necessary for the functionality that ACBLmerge needs. ACBLmerge simply reads full tables using the mdb-export program provided in the mdbtools package.

Note: mdbtools fails if BWS file is copied before it is closed properly by shutting down the electronic scoring system. When it fails, you will not see contracts in the output. The Windows JET driver is sophisticated enough to handle to read improperly closed BWS files but mdbtools is not.

Summary Table of Masterpoint Winners

The -w switch will add a summary table of masterpoint winners near the top of the report. Currently this functionality is only implemented for pairs games. If there are 10 or fewer winners, the results are shown in single column; otherwise the results are shown in a two column format using a smaller font. For the iPhone display the table is always shown as single column.

When displaying the winners for any session other than the final session of a multi-session event, a message is included to indicate that the masterpoint awards are not final.

American Style Scoring

By default, ACBLmerge displays contract results relative to the contract, e.g. 4♠ E +1, for a four spade contract making an overtrick, a format some call European scoring. The -as switch presents the result American style, e.g. 4♠ E 5.

Decorative Features

The -tm (table marker) switch adds a green marker to the center of each deal. This is purely decorative. Long heart or diamond suits in the West hand will overlap the table marker. Although this could be avoided by widening the hand layout area, it seems preferable to conserve screen real estate for the board results.

BridgeBase LIN file output

The -l switch writes the hand records in the BridgeBase LIN format. The LIN format is not fully documented but the output generated by ACBLmerge seems to work in both the Windows BridgeBase program and the online BridgeBase Handviewer. However to use the BridgeBase Handviewer, it is necessary to wrap <lin> and </lin> tags around the start and end of the LIN output and rename the file extension from .lin → .xml. Then it can be referred to using the linurl parameter as in the example below.

http://www.bridgebase.com/tools/handviewer.html?linurl=http://lajollabridge.com/Software/ACBLmerge/linsample.xml

This is explained in the section “Loading an external .lin file through a parameter” of the Handviewer documentation.

If a hand record has been supplied and double dummy analysis has been chosen, ACBLmerge writes the par contract for each board. Often this is not the most realistic contract. For example, you may see 5N listed when the most likely contract would be 3N+2. Worse you may see low percentage contracts that happen to make double dummy or even less likely sacrifices against low percentage or unbiddable games and slams. As always, double dummy results must be taken with a healthy dose of skepticism and par contracts with even more skepticism.

Taking Advantage of Multiple CPUs/Cores

ACBLmerge 1.3.0 and later will automatically use all CPUs/cores when performing double dummy analysis on Windows or Mac OS X computers with multiple CPUs or multiple cores on one or more CPUs, e.g. an Intel Core 2 Duo computer.

On Unix, ACBLmerge 1.33 does not know how to determine the number of cores. The -c option must be specified in order to use multiple cores. The following command line example (-c 4) is for a quad core computer.

perl ACBLmerge.pl -h 080914A.dup -r 080914A.htm -g Sep14.gib -p Sep14.pbn -o Sep14.htm -dd -t "Sep 14, 2008 Unit Game" -c 4

Reusing Double-Dummy Analysis for Multiple Events

Double dummy results will be written to the output PBN and GIB files when the -p or -g switches respectively are specified if requested (-dd switch). The -dd switch will not recompute double dummy results if they are available for every board in the input PBN or GIB file. When several games are played with the same set of hands, the double dummy results may be reused from the PBN or GIB file to very quickly generate results for other games. This is particularly useful for Sectional, Regional, and National tournaments, but relevant even to large clubs running multiple games simultaneously. An example is shown below.

perl ACBLmerge.pl -h 090409A.dup -r 090409A_open.txt -g -p -o -dd -pdf -iphone -t "Thu Afternoon Open Pairs" -pbnevt "Thu Afternoon Pairs"
perl ACBLmerge.pl -h 090409A.gib -r 090409A_299er.txt -g -p -o -dd -pdf -iphone -t "Thu Afternoon 299er Pairs" -pbnevt "Thu Afternoon Pairs"

Here the results files are explicitly given as 090409A_open.txt and 090409A_299er.txt because there is a separate result from each game even though they use the same set of hands stored in 090409A.dup. In the second command, 090409A.gib, generated by the first command, is used instead of 090409A.dup to avoid the need to recompute the double dummy results (the -dd switch is still necessary to have the double dummy results included in the HTML output).

Also note the use of the -pbnevt switch. Normally the Event information recorded in the PBN file, e.g. [Event "Friday Morning Open Pairs"], is automatically taken from the Event> field of the ACBLscore report. But in the case where multiple events use the same boards, it is preferable to override this behavior, e.g. setting it to "Friday Morning Pairs", dropping "Open" since the boards apply to all morning events. Though not essential, this practice is more accurate, avoiding potential confusion when say a player looking at the PBN file linked from the 299er pairs sees "Open Pairs" in the PBN file.

Note: Dealmaster Pro stores double dummy results to PBN or GIB files when asked to perform double dummy calculations. However, in its default mode, it only computes double dummy results for “likely” contracts and writes partially erroneous double dummy information. ACBLmerge will detect this situation and recompute the double dummy results. If you have used the -p and/or -g switch, you can avoid this a second time by feeding the PBN or GIB file created by ACBLmerge into the next event that uses the same hands.

Computing the field strength and displaying masterpoint totals

The -fs switch will compute the field strength in two ways, as the average of each player’s masterpoint total and as the geometric mean of each player’s masterpoint total. In a geometric mean, the mean is taken in a logarithmic manner. For example, the geometric mean of two players with 10 and 1000 MP respectively is 100 MP, rather than 505 MP. Less experienced players drag down the geometric mean more than the arithmetic mean. A field with a high geometric mean should in principle be uniformly tough and offer few gifts. I have argued that geometric mean is probably more meaningful, at least for the distribution of players at tournaments.

The -mp switch adds a “tooltip” display of each player’s approximate masterpoint total when the mouse pointer is held over the player’s name at the top section of the HTML report.

Both the -fs and -mp switches require an ACBLscore game file in order to read the player numbers unless the ACBLscore report includes the player numbers. If a game filename is not specified, ACBLmerge will automatically generate a filename based on the results filename. For example, if the results file is 110214A.txt, ACBLmerge will use the A (or E, M, L) to automatically generate 110214.ACA. If the automatically generated game file is not found in the same directory as the Results file and you are running on Windows, ACBLmerge will also look in C:\ACBLSCOR\GAMEFILE, ACBLscore’s default installation directory.

Note: I haven’t figure out whether the inclusion of player number in ACBLscore reports is controlled by an ACBLscore setting or only happens when older versions of ACBLscore are used. It seems like ACBLscore reports frequently included player numbers until sometime in 2009.

The -fs and -mp switches require the ACBL Club Update database. If you are connected to the internet, ACBLmerge will automatically download the file. It will also automatically download an update if you have a previous month’s database and are running ACBLmerge after the 10th of the month (updates usually appear on the 7th of the month). If you already have an older copy of the database and ACBLmerge is unable to download an update, it will use the older copy.

Face View

The -fc switch adds a “tooltip” image for each player for whom there is an image stored on your web server. This is intended to show faces though any image can be used. The -fc switch may be used in conjunction with the -mp switch. The -fc switch requires an ACBLscore game file in order to read the player numbers since the player numbers are used as the retrieve the images from your server. The advantage of using player numbers rather than names is that they are unique and permanent for ACBL members.

In order to support face view, you must perform several steps on your web server.
  1. Create a folder on your server for the player images. The recommended location is /images/faces
  2. Upload player images in the JPEG image format where the filename matches the player’s all numeric ACBL player numbers, e.g. 1182730.jpg. To convert a life master’s player number to an all numeric player number change J → 1, K → 2, etc. A reference table is provided below. If your web server is configured to be case sensitive, be sure to use a lowercase .jpg file extension. Do not use .jpeg.

    J1 M4 P7
    K2 N5 Q8
    L3 O6 R9

    The images may be any size and do not all need to be the same size. My recommendation is to use roughly 150 x 150 pixel images so they contain good detail but still load quickly from your server. For headshots, I’ve found a 4:5 aspect ratio works well, so most of my images wind up being 150 pixels high and 120 wide. If you do not want to pay for a professional tool like Adobe Photoshop, I highly recommend the free Paint.NET program for cropping, resizing, and other image adjustment.

    You may add or delete images from the server folder at any time without performing any extra steps. Also the folder may contain other images or files if desired (e.g. an alternative image); the ACBLmerge software will only look for those matching #######.jpg, ignoring all others.

  3. If you use a folder other than /images/faces, edit facejson.pl, changing the value of my $FACE_DIR. It is also possible that you will have to hard code the value of my $INTERNAL_FACE_DIR instead of using the value derived from $FACE_DIR.
  4. Upload facejson.pl to /cgi-bin on your server. Make sure it is executable by your web server, e.g. on a Unix based web server, you probably want to run chmod 744 facejson.pl
  5. Test facejson.pl by typing http://yourdomain/cgi-bin/facejson.pl in your web browser. If you do this in Google Chrome or Safari, you should see something like the following where the player numbers are sorted:

    [ "/images/faces/", [ 1015621, 1137379, … ] ]

    If you do this in Internet Explorer, you will be prompted to download the data to a file and the file data should look like the above, but without any spaces. Firefox will behave similarly unless you have the JSONView Add-on installed in which case it will behave like Chrome and Safari.

When face view is selected, the JavaScript embedded in the ACBLmerge output makes an initial JSON request to the server to obtain the location of the player image folder and a list of ACBL player numbers for players with images. This technique eliminates requests for player images that do not exist on your server and avoids unnecessary 404 errors in your web server error logs.

If your web server does not support Perl or you wish to use an alternative server side solution such as PHP, you must recode the simple functionality provided by facejson.pl in the language of your choice and then change var FACEJSON in ACBLmergeCommon.js to your alternate JSON provider. Important: the player numbers must be sorted in your JSON output because the client side JavaScript uses a binary search to maintain good performance even when there are a large number of available images.

Running the software for team games

Most team games are shuffle-deal-and-play. This means hand records are usually not available for teams games. Nevertheless, the field strength, masterpoint tooltip, and face view options are still applicable. And simply converting the non-standard HTML generated by ACBLscore into standards compliant HTML is useful. Therefore, ACBLmerge supports a subset of the pairs functionality.

Save the team results from ACBLscore in the “Press + Recap” format as a text or HTML file. From within ACBLscore, navigate as follows: Reports (menu) → Recap/Press (menu) → Screen/File (LR) → 3. Press + Recap. If prompted whether to “Include Cities and States” choose Yes or No as you prefer.

Note that some team games are saved in ACBLscore files with the .ACB file extension. To load these files into ACBLscore, the program must be in Tournament Mode. In Tournament Mode the (B)oth option will be included at the bottom of the dialog your see after File (menu) → Open as part of the “(M)orning, (A)fternoon, (E)vening, (L)ate, (B)oth” message. You can switch between Tournament Mode and Club Mode via Configuration (menu) → Tournament Mode / Club Mode.

Basic operation is as simple as:

perl ACBLmerge.pl -r 080914_swiss.txt -o

The output filename will automatically be named 080914_swiss.htm. Unlike the HTML generated by ACBLscore, the ACBLmerge HTML output will be standards compliant. Since no title is specified, the title for the HTML document will automatically be generated based on the event date and event name, e.g. “May 29, 2011 Sun Strat Swiss Teams”.

If you want to include the field strength color bar, masterpoint tooltip, and face view, add those options:

perl ACBLmerge.pl -r 080914_swiss.txt -o -fs -mp -fc

If hand records are available you may use the -h, -p, -g, and -pdf options as you would for pairs results. These will create links at the top of the HTML output to the relevant files but no hand diagrams will be included in the main HTML file. Double dummy analysis may be invoked with the -dd option. The double dummy results will be included in the PBN and/or GIB output files.

For team games there is no support for Bridgemate / BridgePad data. Therefore, the -b option is not applicable.

Website Integration Features

In order to integrate ACBLmerge output seamlessly into a sophisticated website you may wish to add a common header image, menubar, footer, or other features. ACBLmerge provides the -ih (insert head), -isb (insert start body), and -ieb (insert end body) switches for inserting content from user supplied files directly into the ACBLmerge HTML output just before the </head> tag, just after the <body> tag, and just before the </body> tag respectively. The following code is a simple example that might be included with the -isb switch to add a club banner at the top of each results page

<img src="/images/banner.jpg" width="800" height="80" alt="club banner" />

ACBLmerge does not perform any validation on user supplied HTML. Therefore, users should be sure to validate the combined result using a program such as the free Total Validator or the excellent CSE HTML Validator which I found very useful for the development of ACBLmerge.

Sophisticated users who wish to alter aspects of the ACBLmerge appearance but do not wish to directly alter the ACBLmerge.css file can simply override the CSS as appropriate by using the -ih option.

By default the “Explanation of Features” link at the top of the HTML report will point to the explanation on the La Jolla Unit website. If you want to keep users on your website, place a copy of the ACBLmergeReport.htm and ACBLmergeReport.png files on your website and use the -hurl switch to have ACBLmerge output point to your copy. For example:

perl ACBLmerge.pl -h 080914A.dup -g -p -o -dd -w -hurl "/ACBLmerge/ACBLmergeReport.htm"

You can also use the -nohurl switch if you do not want a link to the help.

The -cgip switch is provided to link player names to a CGI interface. The argument supplied to the switch will be used as the base URL. Either ?pnum=####### or ?pname=Full Name will be appended to the base URL to create the hyperlink. For example, -cgip /res_player.cgi will create hyperlinks like the following:

/res_player.cgi?pnum=8535043
/res_player.cgi?pname=Philippe%20Lamoise

The ?pnum form containing the player’s all numeric ACBL player number will be generated if the player number is available. This requires one of the -fs, -fc, or -mp switches to be specified. Otherwise the ?pname form with the player’s full name will generated. All spaces and special characters will be properly escaped according to CGI standards.

The player links are “hovering” links that only appear when the mouse pointer is position over the player name. If ordinary “permanent” links are desired, edit ACBLmergeCommon.css, changing none to underline in the definition of the .hoverlink class.

The -mssurl switch adds the message “View overall rankings for all sections and/or sessions” underneath the table of masterpoint winners and links it to the URL specified. Although the awards shown on the final session of a multi-session event are the better of the sum the individual awards from each session and the overall performance across each session, ACBLscore does not show the average percentage across all sessions. This switch can be used to direct players to a web page that does. Similarly when a large event with many sessions is broken into multiple separately combined sections, e.g. JKL and MN, this switch can be used to direct players to a web page that show overall ranking across all sections. Note: this switch does not create such pages; it only allows a link to be created to them.

CGI backends may not provide an environment variable that ACBLmerge can use to generate an application directory. The -appdir switch may be used to explicitly define the application directory. See the User Application Folder section below.

The -giburl, -pbnurl, -linurl and -txturl switches allows the URLs for the GIB, PBN, LIN, and TXT files (“View original ACBLscore output”) at the top of the report to be explicitly defined. This is useful if the GIB, PBN, or input text files will not be placed in the same directory as the HTML output on the web server. See the Uploading section.

Data Mining Output File

The -dm switch creates JSON output containing information about the event and the pairs or teams in the event. This feature was implemented to support functionality on the bridgeresults.net website but may be useful to anyone who does not want to manually parse ACBLscore output with its many slightly different cases.

Note: The data mining output described here is the result of parsing the text based ACBLscore reports. It was developed before the binary ACBLscore game file format had been reverse engineered. Currently, programmers are recommended to start with ACBLgamedump, a utility that can directly read the binary game files.

The top level JSON structure always includes two administrative fields:

Field Mode Description
creator both Program that created JSON output. ACBLmerge writes "ACBLmerge" followed by its version, e.g. "ACBLmerge 1.3.2".
version both Version of JSON output format. ACBLmerge 1.3.2 creates version 2, with the implicit assumption that earlier output was version 1 although no version field was written previously.

The top level of the JSON structure always contains an event field. Depending on the value of event.gametype, other fields will be present. Pairs and team events contain the pairs and teams fields respectively. Team events also contain the players field. Board-a-Match (BAM) events contain the teams field but not the players field. The following is an sample of the event data. Note: In the actual file, the only white space will be within quoted fields and the order of the fields is arbitrary.

"event":{
"gametype": "pairs",
"event": "Sunday Afternoon Pairs",
"session": "Sunday Aft",
"datestr:" "December 28, 2008",
"club": "La Jolla Unit",
"rating": "Unit Championship",
"nstrats:" 3,
"strats": "ABC",
"mplimits": ["None", "2500", "500"],
"finalAwards": 1,
"hasPct: 1,
"sections": ["A", "C"],
"movement": "MITCHELL",
"director": "Michael Weber",
"clubnum": "146506",
"lastmod": "12/28/2008 15:38",
"top": "12",
}

Most of these fields are pulled straight from the ACBLscore file. The fields gametype, sections, finalAwards, fs, hasPct, nstrats, and strats are derived from other data.

The table below describes all the event fields and whether they appear when ACBLscore is used for a club game or a tournament game, or in both cases.

Field Mode Description
boardsPerRound both Number of boards per round. Only present for team games and may be null.
city tourn City that tournament is held in
club club Club name
clubnum club Club number, e.g. “146506”. Always six digits.
datestr both Date of event in “Month DD, YYYY” format.
director both Director name
event both Event name
eventcode tourn Numeric event code for type of event. Not yet decoded.
finalAwards both 1 if the masterpoint awards are final; otherwise 0. This field will be 0 in all sessions except the last of a multi-session event, e.g. a two session Morning and Afternoon pairs events.
fs both Field strength data. See follow up table.
gameformat both Team game format such as “VICTORY POINT”.
gametype both Either “pairs” “teams”, or “BAM”.
hasPct both 1 if each pair has a percentage; 0 if not, e.g. for an IMP pairs event where percentage is not defined.
hasOverallRanks both 1 if result has Overall rankings in addition to Section rankings; otherwise 0.
isMultiSession both 1 if the event contains multiple sessions; 0 if not.
lastmod both Date and time of last modification may to ACBLscore game file by ACBLscore. Format is “MM/DD/YYYY HH:MM” in 24-hour format.
movement both Player movement. Examples: MITCHELL, HOWELL, ONE WINNER, WEB.
mplimits both Array of masterpoint cutoffs for each strat. For an open event the highest strat will be “None”.
nstrats both Number of strats in a stratified event. Set to 1 for a non-stratified event.
rating both Masterpoint rating. Examples: “Club Masterpoint”, “Unit Championship”, “Junior Fund”, “Club ACBL Membership”, “STAC”, “North American Pairs - Unit”, “Sectional”, “Regional”.
sanction tourn Tournament sanction, e.g. “R1112022” Format is LYYMMDD# where YYMMDD is the start date of the tournament, # distinguishes multiple sanctions issued for the same start date, and L is “S” for sectionals and “R” for regionals.
sections both Array of section designations sorted alphabetically. Section designations are either a single capital letter or a repeated capital letter. Do not assume that a club running only one game at a time uses section “A”.
session both Name of session. Examples: “Morning” or “Afternoon”.
strats both Name of strats, one character per strat, e.g. “ABC”, “AX”, or “DEF”. Some events have numerical strats, e.g. the “7” and “3” seen in regional Gold Rush pairs. Thus a string like “73” is not an error.
top both Score for a top board. Will be null if hasPct field is 0.
tournament tourn Tournament name, e.g. “Palm Springs Regional”. Beware: this field is not set consistently to the same name for all events in the same tournament. It is better to rely on the Sanction code to test if file are from the same tournament.

The field strength fields are given below:

Field Description
mean Average masterpoint holding of all players in the field who are ACBL members and for whom masterpoint data is available.
geomean Geometric mean of masterpoint holdings (as above).
nData Number of players used to calculate mean and geometric mean.
nFail Number of ACBL players for whom masterpoint lookup failed.
nNonMember Number of non-ACBL players.

For a pair event, each pair is identified by a pair_id. The pair_id has the from {section}{num}{dir}, e.g. “B12E”. The direction is either “N” for a N-S pair or “E” for an E-W pair. For Howell movements, the direction component will not be present, e.g. “A5”.

The possible fields for each pair are given in the table below:

Field Description
player1 Full name of first player in partnership.
player2 Full name of second player in partnership.
pnum1 All numeric player number of first player in partnership. This field is not present if no player numbers are available. It is null if an individual player can not be resolved to a player number.
pnum2 All numeric player number of second player in partnership.
Flt Flight if event is stratified, e.g. “A”. If the event is not stratified (nstrats == 1 above), this field will not be present. Flt will always match one of the characters in the strats event field.
Pct Percentage. In a multi-session event, this is the percentage achieved in the session, not the average of all sessions played. If the strats event field is 0, percentage is not meaningful for the scoring method (e.g. IMP Pairs) and the Pct field will not be present. In this case use the Score field to rank pairs.
Score Sum of matchpoints or IMPs from all boards played by the pair. This field is most useful for IMP Pairs when the Pct field is not present.
Carryover Carrover of matchpoints or IMPs from all boards played by the pair in previous session(s).
Total Total of all matchpoints or IMPs from all boards played by the pair across all sessions in the event.
Awards Comma separated list of masterpoint awards. Each awards is a number, optionally followed by a space and a pigmentation identifier such as Red, Silver, or Gold. If no pigmentation identifier is given, Black should be assumed. An empty string indicates the pair received no masterpoints. If the finalAwards event field is 0, the awards should not be included in calculation of a player’s total.
Reason Reason for award, e.g. “OB” for Overall in B strat. For example, a pair that places 5th overall in A and 1st overall in B will receive whichever award is greater. The Reason field indicates which award was chosen. This field is not available for tournament results (ACBLscore doesn’t have enough room to print it).
Rnk1S Section Rank in highest strat (even if the highest start is not designated as “A”) if pair received masterpoints; otherwise an empty string. If there is a tie for ranks M-N, the rank will be designated “M/N”. This field will be provided even for unstratified events.
Rnk2S Section Rank in 2nd highest strat (provided pair’s flight allows them to be ranked in this strat). Field is not provided if the event is unstratified.
Rnk3S Section Rank in 3rd highest strat (provided pair’s flight allows them to be ranked in this strat). Field is not provided if the event does not have three strats.
Rnk1O Overall Rank in highest strat (as above)
Rnk2O Overall Rank in 2nd highest strat (as above).
Rnk3O Overall Rank in 3rd highest strat (as above).
Adjust Present if there is an adjust due to procedural penalties. If present, the field will be supplied for all pairs in a section but not necessarily all pairs in the event.
SectTableDir Location of pair in next round of a multi-session event.

Note: Fields for lower ranking strats will only be present if the event has those strats. Single section events will not have fields for section strats.

Each board is usually identified by a positive integer but indexed as a hash for efficient storage if the boards are not numbered 1-N or some other identification scheme is used. Information about a given board can be accessed via boards{#} where the possible fields for each board are listed below. The gibdd, parNS, parEW, parContracts, totalTricks, and totalTrumpss fields are only present if a hand record is supplied and double dummy results are calculated (-dd switch)

Field Description
deal The deal, in PBN format, e.g. W:KQ9874.954.T63.2 T2.AK.K82.AKQT83 3.QT87.AQJ7.9764 AJ65.J632.954.J5 where spaces separate the hands, periods separate the suits in each hand, T is used for 10, and W: indicates the first hand is West, the remaining hands proceeding clockwise. This field will not be present if a hand record is not supplied or a hand is missing from the supplied hand record.
gibdd Double dummy analysis for the deal in the compact GIB format, e.g. A9A9656698978777A9A9 where the black, blue, red, orange, green groups respectively are the number of tricks N-S can take in no trump, spade, heart, diamond, and club contracts respectively, when the lead is in each of the four seats. In this hexadecimal notation, A=10, B=11, C=12, and D=13. Each group of four characters is the result when the lead in the South, East, North, and West seats respectively, corresponding to East, North, West, and South respectively as declarer assuming no abnormalities such as a lead out of turn. Note: This order is counterclockwise, the opposite direction of bidding and play at bridge!
parNS Par result from perspective of N-S assuming N-S bids first.
parEW Par result from perspective of N-S assuming E-W bids first. This value nearly always matches par_ns, but in rare cases, for example when each side can make 1N provided it bids it first, the values will be different (90 and -90 in the 1N example).
parContracts Array of par contracts. Makeable contracts are always at the highest level makeable and include all directions that can make, e.g. "5S-N", "5S-S", or "5S-NS". Sacrifice contract are always doubled and include all seats from which this is the par contract, e.g. "4D*-E-2", "4D*-W-2", or "4D*-EW-2". If neither side can go positive by bidding the par contract is "PASS". In “hot” situations where par_ns and par_ew are not equal, the list of seats may include seats from both directions, e.g. "1N-NSEW".
totalTricks Total number of tricks according to the Law of Total Tricks.
totalTrumps Total number of trumps according to the Law of Total Tricks.
results An array of results for the board, one element for each time it was played. Each element in turn contains an array that is detailed in the next table.

Each individual result array contains the first 5, 10, or 11 elements below depending on whether contract information is available from Bridgemate / BridgePad scoring systems and whether the devices have been set to capture the opening lead.

Index Description
[0] The score for N-S, e.g. "400" or "-150". If deal is passed out "0" will be recorded. The score may also be "Ave", "Ave+", "Ave-", or "NP" (Not Played) as the result of director rulings. The E-W score is normally the opposite of the N-S score. In rare cases, the score will contain two values split by a pipe symbol, e.g. "-200|Ave+" This indicates a split score where N-S was assigned -200 and E-W was assigned Ave+. "NP" should only be seen in the context of a split score where one side was the clear offender; if a board was not play due to slowness on the part of both pairs, there will no result to report.
[1] Matchpoint score for N-S. The percentage can be derived by dividing this number by event.top.
[2] Matchpoint score for E-W. Normally this is the same as the N-S matchpoint score subtracted from event.top but in the case of a split score it can be different.
[3] N-S pair identifier. This will match a pair identifier used to index the pairs field, e.g. "K5N", e.g. N-S pair 5 in section K. Single section events will lack a section identifier. Pair numbers for Howell movements will also lack a direction identifier (N or E) since pairs change direction during Howell movements.
[4] E-W pair identifier, e.g. "K8E" similar to last field.
[5] Contract level, i.e. 1-7 or "PASS".
[6] Contract denomination: C, D, H, S, or N. If the contract is doubled or redoubled, the denomination will be followed by one or two asterisks respectively, e.g. "S*". Empty string if hand is passed out.
[7] Declarer: N, E, S, W. Empty string if hand is passed out.
[8] Number of tricks taken relative to the contract level, e.g. "-1", "0", or "+2". Empty string if hand is passed out.
[9] Extra Trick Factor (ETF). Number of tricks better or worse that declarer achieved relative to the double dummy expectation. Value will be undefined if no hand record is supplied or the contract is passed out.
[10] Opening lead, e.g. "H8" If the lead is followed by an equals sign, the card led was in the hand of the opening leader’s partner. If the lead is followed by an question mark, the card led was in the hand of one of the opponents. Empty string if hand is passed out.

Each team is identified by a positive integer. The possible fields for each team are given in the table below:

Field Description
players Array of player names. Teams will have at least four players and may have up to six.

For teams events, player information is reported separately because when a team does has more than four players, the award may be different for different team members depending on how many rounds or sessions the team member played. The possible fields for each player are given in the table below:

Field Description
pnum All numeric player number of first player in partnership. This field is not present if no player numbers are available. It is null if an individual player can not be resolved to a player number.
Award Comma separated list of masterpoint awards. Each awards is a number, optionally followed by a space and a pigmentation identifier such as Red, Silver, or Gold. If no pigmentation identifier is given, Black should be assumed. An empty string indicates the pair received no masterpoints. If the finalAwards event field is 0, the awards should not be included in calculation of a player’s total.
Reason Reason for award, e.g. “OB” for Overall in B strat. For example, a pair that places 5th overall in A and 1st overall in B will receive whichever award is greater. The Reason field indicates which award was chosen.

Board-a-Match (BAM) events contain a team field but it more closely resembles the pairs field above than the teams field for ordinary teams games. However, the fields player1, player2, pnum1, and pnum are replaced by two new fields:

Field Description
players Array of player names (four to six elements).
pnums Array of player numbers. Array has same length as players array and each player number is for the corresponding element in the players array. A value of undefined indicates a player without a player number.

Line Termination

ACBLmerge uses the :crlf Perl I/O layer to ensure that any input files with Windows style line termination (CR LF) will be correctly handled when running on Unix. By default, output files will be created using the line termination of the OS that the application is run on. However, the -crlf option can be used to force the use of Windows style line termination for all text based output files.

User Application Folder

The masterpoint database (see Computing the field strength) and intermediate files used during the double dummy calculation are stored in a per user application specific folder. This ensures the user can create/update these files even if the user only has read permission on the ACBLmerge application folder, the one containing ACBLmerge.pl and its support files.

On Windows, the application folder is %APPDATA%\ACBLmerge, e.g. C:\Documents and Settings\username\Application Data\ACBLmerge on Windows XP or C:\Users\username\AppData\Roaming\ACBLmerge on Vista and Windows 7. On other platforms it is ~/.ACBLmerge, a hidden folder in the user’s home directory. The home directory is determined by the HOME environment variable.

If the HOME environment variable is not available on a non Windows platform, an application directory may be explicitly defined using the -appdir switch. For CGI use, the application directory should remain the same between invocations to prevent repeated downloads of the masterpoint database. Temporarily files are distinguished by the process id ($$ in Perl) and therefore should not collide.

If ACBLmerge can not create the application folder when needed, it will exit with an error.

Double Dummy Analysis Technical Details

For Windows, Bo Haglund’s double dummy solver is provided as a DLL (dds.dll). Starting with ACBLmerge 1.3.0, the application uses a new program ddsolver.exe on Windows to communicate directly with this DLL. For Mac OS X, ddsolver is statically linked to the DDS code. The file mac-os-x/dds.a is the static library if you want link your own code against DDS.

Previously, ACBLmerge used a command line based front-end for DDS called the Double Dummy Driver (DDD) written by P.M. Cronje. This was an expedient solution that saved me the effort of learning how to call functions in Windows DLLs. But it was always a kludge because DDD was designed for a more general purpose. As the years rolled by, being tied to DDD became more problematic. DDD was not maintained and I had trouble compiling it with later, more efficient, versions of 1.1.x DDS series. Then Bo Haglund released the 2.x versions of DDS which had support for multiple CPUs / cores built into the solver. Although previous versions of ACBLmerge took advantage of multiple cores by launching separate DDD processes, this approach had the drawback that double dummy analysis had to wait on the completion of slowest of the last few board(s) when some cores were already idle. With the 2.x DDS versions, all cores are engaged simultaneously for each board, eliminating the inefficiency.

Another advantage of communicating directly with the DLL is that users should be able to upgrade to a later version of the double dummy solver simply by replacing the dds.dll version shipped with ACBLmerge with one downloaded from Bo Haglund’s website. Such is the magic of reusable binaries. Note: if you do this, be sure to choose a version that says “with PBN”.

Unfortunately, DLLs are not portable to non-Windows platforms. So for now other than on Windows and Mac OS X, ACBLmerge still relies on DDD. The easiest way to get a copy of DDD is to install the dds Linux package. For example, on Ubuntu (Debian) use one of the following commands or use the Synaptic package manager.

apt-get install dds (if running as root)
sudo apt-get install dds (if you are allowed to install packages)

If you go this route, the package installed executable will be named dds instead of ddd because ddd was already taken by another Linux package, the Data Display Debugger. Just copy dds (look in /usr/games) to the directory where ACBLmerge is installed and rename it ddd.exe.

Alternatively you can compile DDD. The DDS and DDD source code is straight C++ so it should compile and run under any platform. On Linux and Unix I compile it using the open source GCC compiler. You can download a gzipped tar file of source code from here. The start of the file ddd.cpp has some notes about compilation. After compilation, rename ddd to ddd.exe and drop ddd.exe into the same directory as the ACBLmerge.pl Perl script or into any directory with is on the executable search path. Note: ACBLmerge will always check the folder it is located in for ddd.exe whether or not that folder is on the search path before trying the search path.

If you can’t install the ddd package, can’t get it to compile, or are feeling really lazy, you can try the executables provided in the executable subfolder of the gzipped tar in the preceding paragraph. If one works, rename it to ddd.exe and proceed as above.

Note: If you are using a version of ACBLmerge prior to 1.3.0 on Windows and need a precompiled version of ddd.exe you can downloaded it from Bo Haglund’s website as a zip file or from the La Jolla bridge website as a zip file. The copy on the La Jolla bridge website is DDS 1.1.9 (2008) linked against DDD 1.0.5 compiled with gcc 3.4.4; it requires the included cygwin1.dll file to run unless you already have the Cygwin package installed.

Command Line Help

Command line arguments in [ ] are optional; for example [-r [resfname]] means the -r switch is optional and that if it is specified, following it with filename is also optional.

To do anything useful, either the -h or -r switch must be specified along with a filename. Also, you will almost always want the -o switch.

  Usage: ACBLmerge.pl [-h handfname] [-r [resfname]] [-b [bwsfname]]
  [-o [outfname]] [-g [gibfname]] [-p [pbnfname]] [-l linfname] 
  [-pdf [pdffname]]  [-txt [txtfname]] [-dd] [-t title] [-iphone]
  [-pbnevt event_name] [-hurl URL] [-w] [-tm] [-c #] [-fs [gamefname]]
  [-mp [gamefname]] [-fc [gamefname]] [-v] [-q] [-crlf] [-giburl URL]
  [-pbnurl URL] [-linurl URL] [-txturl URL] [-mssurl URL] [-ih headfname]
  [-isb sbdyfname] [-ieb ebdyname] [-appdir dir] [-cgip URLbase]
  [-dm [dmfname]]  
  
  handfname : Hand record filename (Duplimate, PBN, or GIB format)
  resfname  : ACBLscore results filename. Default extension is .txt
              Can also read HTML files generated by ACBLscore.
  bwsfname  : Bridgemate / BridgePad filename. Default extension is .bws
  outfname  : HTML output filename. If the -o option is not specified,
              output is sent to STDOUT. Default file extension is .htm
  gibfname  : Write hands in Goren in a Box (GIB) library format. If -dd is
              also specified, GIB file will contain the makeable contracts.
              Default file extension is .gib
  pbnfname  : Write hands in Portable Bridge Notation (PBN) format. Default
              file extension is .pbn
  linfname  : Write hands in Bridge Base (LIN) format. Default file
              extension is .lin              
  pdffname  : Specifies filename or URL for PDF hyperlink in output HTML.
              Typically this target would be PDF file produced by Dealmaster
              Pro for printing paper copies of the hand records.
  txtfname  : Specifies filename for plaintext output (sometimes desired if
              original ACBLscore output was in HTML)
  gamefname : ACBLscore game filename. Required for field strength (-fs)
              option, as well as the masterpoint (-mp) and faces (-fc) 
              tooltip display options.
  dmfname   : Specifies filename for data mining JSON.

  To do anything useful, either the -h or -r option must be specified along
  with a filename.  
  
  If a filename is not supplied for any of the -r, -g, -p, -l, or -pdf switches
  the filename is automatically generated by changing the file extension of the
  full filename of the hand record filename, i.e. .dup/.pbn/.gib/.bri -->
  .txt, .gib, .pbn, .lin, or .pdf respectively.
  
  If a filename is not supplied for any of the -b, -txt, -o, -iphone, -dm, -fs,
  or -mp switches, the filename is automatically generated by changing the
  file extension of the full filename of the ACBLscore results filename, i.e.
  .txt/.htm --> .bws, .txt, .htm, .htm, .json, .ACA/.ACE/.ACM/.ACL (last two)
  respectively.  
  
  Options
    -dd     - Include double dummy makes, par contract, and LoTT statistics
    -t      - Specify title of HTML output. If not specified, the title
              defaults to "Mmm DD, YYYY Game Result" where the date is
              derived from the DATE> header of the ACBLscore file.
    -w      - Include list of masterpoint winners at top of output.          
    -iphone - Create additional output HTML file for viewing on the iPhone.
    -pbnevt - Defines Event Name to be used in PBN output. If not specified
              PBN output uses the Event Name from the ACBLscore results file.
    -fs     - Include field strength calculation
    -mp     - Include player masterpoints (hovering tooltip over player names)
    -fc     - Show players faces (hovering toolip over player names)
    -tm     - Include table marker in the center of each hand.
    -as     - Use American Style contract notation, e.g. 2S 9, instead of 2S +1    
    -crlf   - Write Win32 style newlines (CR LF) even when running on Unix.
    -c      - Specify number of CPUs (cores) to use for double dummy analysis.
    -q      - Quiet mode. Do not print any informative messages to STDERR.
    -v      - Print program version on STDERR (overrides -q)

  Advanced Options
    -ih     - Specify file of HTML code to insert in the <head> element of
              the output. Code is added after ACBLmerge <head> content.
    -isb    - Specify file of HTML code insert at the start of the <body>
              element; for example to include a menu bar or banner.
    -ieb    - Specify file of HTML code to insert at the end of the <body>
              element; for example to include contact information.
    -crlf   - Write Win32 style newlines (CR LF) even when running on Unix.    
    -hurl   - Specify URL that explains features of ACBLmerge.pl output
              This is used to create a link at the top of the HTML output.
              Example: -hurl "/software/ACBLmergeReport.htm". Defaults to
              http://lajollabridge.com/Software/ACBLmerge/ACBLmergeReport.htm
              if -hurl is not specified.
    -nohurl - Do not include a help link, not even the default.
    -giburl - Specify URL to GIB file (only required if GIB file will not be
              placed in same directory as HTML output file on the web server)    
    -pbnurl - Specify URL to PBN file (only required if PBN file will not be
              placed in same directory as HTML output file on the web server)
    -linurl   Specify URL to LIN file (only required if LIN file will not be
              placed in same directory as HTML output file on the web server)              
    -txturl - Specify URL to text file (only required if PBN file will not be
              placed in same directory as HTML output file on the web server)
    -mssurl - Specify URL to multiple session / section overall rankings           
    -appdir - Explicitly set application directory
    -cgip   - Specify root of hyperlink for player names in results section  

  Note: for clarity the -ih, -isb, -ieb options have the alternate long
  forms of -ihead, -isbody, and -iebody.

  Produces HTML output that merges bridge hands with ACBLscore text results,
  and optionally the contract and/or opening lead information from the
  Bridgemate or BridgePad electronic scoring systems. Hands may be supplied
  in Duplimate format (.dup/.bri), PBN, or GIB (Goren in a Box) library format.
  The GIB format can store double dummy results. The ACBLscore results need
  to be saved in the "traveler format". From ACBLscore navigate Report (menu)
  --> Recap/Press (menu) --> Screen/File (LR) --> 8. Press + Recap
  (traveler format). Or alternatively 9. Short Press + Recap (traveler format).
  The report may be saved in either text or HTML format.

  The HTML output includes advanced clipboard copy features and the HCP count
  for each board. For each board, the pairs are sorted by N-S matchpoints.
  If double dummy analysis is performed, makeable contracts (+number of tricks
  for every contract), the par contract, and a LoTT calculation will also be
  shown. Hands may also be output in Portable Bridge Notation (PBN) format
  for trick by trick double dummy analysis in programs such as Bridgify and
  the Bridge Captain Double Dummy Solver (both free).

  Example: perl ACBLmerge.pl -h 080914A.dup -r -dd -o -p -w

  The input files are 080914A.dup and 080914A.txt (the ACBLscore filename
  080914A.txt is implicitly assumed here because it is required but was not
  supplied). Likewise, the HTML output will default to 080914A.htm since the
  -o switch has no argument. The -dd switch specifies that double dummy
  analysis will be performed. The PBN output will default to 080914A.pbn.
  No GIB output will be generated since the -g is missing.
  
  Online documentation is located at:
  http://www.lajollabridge.com/Software/ACBLmerge/ACBLmergeAbout.htm