ACBLmerge

ACBLmerge is a free program to merge hand records and double dummy results with ACBLscore output and create HTML output for use on websites.

Overview

The American Contract Bridge League (ACBL) ACBLscore program is a very old program, originally written for DOS and minimally ported to Windows. It can generate many text based reports which were originally designed to be printed out. The same reports can also be generated in an HTML format. But the HTML generated by ACBLscore is an extremely minimal effort that simply uses the <pre> tag to display the results as plain text, making no use of the sophisticated document formatting that HTML allows. In fact the HTML generated by ACBLmerge does not even strictly 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 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 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 introduces popup recap sheets for each pair.

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. Such users are automatically redirected to such the customized reported if available when accessing the primary report.

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, and a command line based front-end called the Double Dummy Driver (DDD). DDS is a very efficient solver, requiring about 5 minutes 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 under half a minute.

Perl runs on all major operating systems. The DDS and DDD source code is straight C++ so it should also run under any platform. I compiled it under Windows using the free g++ 3.4.4 compiler running under the Cygwin environment.

ACBLmerge generates clean HTML that validates as HTML 4.01 Transitional. The appearance has been verified under Firefox 3, IE7, IE8, Safari 3.1, and Google Chrome 4.1. 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 ACBLmerge.css file.

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.

Version	Date	Major Changes
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.1	13-Apr-2010	Fixed bugs introduced in version 1.1.0 when multiple CPUs are used to perform double dummy analysis.
1.1.0	07-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 (previous embedded in Perl code).
1.0.8	04-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.7	11-Apr-2009	Mostly bug fixes
1.0.6	07-Apr-2009	Added iPhone / iPod customized HTML output.
1.0.1	25-Sep-2008	Original release.

Obtaining the software

ACBLmerge.pl can be downloaded as a zip (for Windows) or gzipped tar (for Unix) archive.

The archive contains the Perl script ACBLmerge.pl, the application files ACBLmerge.css and ACBLmerge.js, the documentation ACBLmergeAbout.htm, ACBLmergeReport.htm, ACBLmergeReport.png, and ACBLmergeLogo.png, and the revision history Changelog.txt. The fourth file contains the information on this page. The fifth and sixth files explain the ACBLmerge reporting features; after choosing a folder for ACBLmergeReport.htm and ACBLmergeReport.png on your website, you can link to ACBLmergeReport.htm from each ACBLmerge generated webpage via the -hurl command line option.

A precompiled version of ddd.exe for Windows can be downloaded 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; it requires the included cygwin1.dll file to run unless you already have the Cygwin package installed.

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. Perl has been included on Apple computers since Max OS X. Some Linux distributions have Perl pre-installed. ACBLmerge.pl only needs the threads Perl package which is part of the standard Perl installation since 5.6.0.

Install Perl.
Put ACBLmerge.pl, ACBLmerge.css, and ACBLmerge.js together in whatever folder you please. On Windows, C:\Perl, C:\ACBLmerge, or C:\Program Files\ACBLmerge, or your My Documents folder would all be fine.
Put ddd.exe and cygwin1.dll into a directory which is on the executable search path or just put them in the same directory as the ACBLmerge.pl Perl script.

Note: ACBLmerge will always check the folder it is located in for ddd.exe whether or not that folder is on the search path.

Running the software

Results from ACBLscore and the hand information must be available. 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 player rankings from all sections are included. The output will show the same hands results multiple times but that will not affect the ACBLmerge program.

The hand record information must be in Duplimate, 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 presentation 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 (or Unix / Mac). Then type something like:

For XP: cd C:\Documents and Settings\username\My Documents (or wherever you have placed the files)
For Vista: cd C:\Users\username\Documents (or wherever you have placed the files)

perl ACBLmerge.pl -h 080914A.dup -g -p -o -dd -t "Sep 14, 2008 Unit Game" -hurl "/software/ACBLmerge/ACBLmergeReport.htm"

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 a 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 -t switch sets the title of the output web page. And the -hurl switch set the location of the ACBLmerge Report webpage on your website.

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 -t "Sep 14, 2008 Unit Game" -hurl "/software/ACBLmerge/ACBLmergeReport.htm"

Only the -h switch 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. 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 -t is not specified, the date will be determined from the ACBLscore output and the web page title will default to "Mmm DD, YYYY Game Result".

If the output HTML will match the name of the input file (regardless of case), the input file will be renamed, e.g. 080914A.orig.htm, to prevent the original from being clobbered.

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. 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 -pdf -iphone -t "Sep 14, 2008 Unit Game" -hurl "/software/ACBLmerge/ACBLmergeReport.htm"

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.

Taking Advantage of Multiple CPUs/Cores

On computers with multiple CPUs or multiple cores on one or more CPUs, e.g. an Intel Core 2 Duo computer, the -c option can be used to specify how many concurrent ddd.exe executables are spawned to perform double dummy analysis. Specifying a higher number than the actual number of cores will not speed up the processing and instead will actually slow it down very slightly. On Windows, each additional ddd.exe executable requires ~25 MB (Peak Private Bytes). Most computers should easily have enough memory to run as many executables as necessary to use all CPUs/cores; however if memory is tight, memory swapping may occur in which case the number of CPUs/cores used should be reduced. When memory is not a problem, all CPUs should be steadily pegged at nearly 100% utilization during the double dummy analysis. Below is a command line example appropriate for a duo 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" -hurl "/software/ACBLmerge/ACBLmergeReport.htm" -c 2

Reusing Double-Dummy Analysis for Multiple Events

When several games are played with the same set of hands, the double dummy results can be computed once and saved to a GIB file with the -g switch. Then the resulting GIB file can be used as the source of the hand records 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" -hurl "/software/ACBLmerge/ACBLmergeReport.htm"

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" -hurl "/software/ACBLmerge/ACBLmergeReport.htm"

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 precise, avoiding potential confusion when say a player looking at the PBN file linked from the 299er pairs sees "Open Pairs" in the PBN file.

Advanced 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

ACBLmerge does not perform any validation on user supplied HTML. Therefore, users should be sure to validate the combined result using a web service such as Total Validator or a dedicated application such as 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.