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.

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 and BridgePad 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.

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 about one 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 only 10-20 seconds. On non-Windows platforms ACBLmerge uses the open source mdbtools package to read Bridgemate and BridgePad files. On Windows, 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 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 4.01 Transitional. The appearance has been verified in Firefox versions 3-14, Internet Explorer versions 7-9, Safari 3.1, and Google Chrome versions 4-21. 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.

Version	Date	Major Changes
1.3.4  ⇓	29-Jan-2013	Added preliminary support for Board-a-Match (BAM) events. Switched to 7-zip to read compressed masterpoint database on Windows.
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.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 (previously 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-2010	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. 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.

Filename	Purpose
ACBLmerge.pl	Application file (PERL script)
ACBLmergeCommon.js	Application support file (JavaScript)
ACBLmergePairs.js	Application support file (JavaScript)
ACBLmergeCommon.css	Application support file (CSS)
ACBLmergePairs.css	Application support file (CSS)
ddsolver.exe	Double dummy solver (executable)
dds.dll	Bo Haglund’s double dummy solver (DLL)
7z.exe	7-zip archive (Version 9.2.0, 32-bit executable)
7z.dll	7-zip archive (Version 9.2.0, 32-bit DLL)
ACBLmergeAbout.htm	Documentation for ACBLmerge user
ACBLmergeLogo.png	Documentation for ACBLmerge user (support file)
download.png	Documentation for ACBLmerge user (support file)
ACBLmergeReport.htm	Documentation for bridge players
ACBLmergeReport.png	Documentation for bridge players (support file)
Changelog.txt	Detailed revision history
facejson.pl	Server side support file for face view feature
ddsolver.cpp	C++ source code for ddsolver.exe
dll.h	C++ header file for compilation of ddsolver.cpp

The nine files marked in blue are required to use the full functionality of the application. The second set 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.

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.
   
   

   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 either the Bridgemate or BridgePad 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.

3. Non-Windows only: 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 the ddsolver.exe program included in the archive will do the double analysis.

4. Non-Windows only: Install the mdbtools package if you want to include results from either the Bridgemate or BridgePad 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 and URI 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, LWP::UserAgent, Archive::Lha) and their dependencies. 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 might not work on Vista or Windows 7 and in any case will likely require administrator permission.

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.

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 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:

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.

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.

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.

Switch	Base filename	New extension	Use
-r	Hand filename	.txt	Input file
-g	Hand filename	.gib	Input or Output file
-p	Hand filename	.pbn	Input or Output file
-l	Hand filename	.lin	Output file
-pdf	Hand filename	.pdf	Input file
-b	Results filename	.bws	Input file
-o	Results filename	.htm	Output file
-iphone	Results filename	.htm	Output file
-txt	Results filename	.txt	Output file
-dm	Results filename	.json	Output file
-fc	Results filename	.ACM/.ACA/.ACE/.ACL*	Input file
-fs	Results filename	.ACM/.ACA/.ACE/.ACL*	Input file
-mp	Results 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.

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 Bridge Scorer 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 Bridge Scorer 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)” 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.

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.

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 write 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 records 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 computers with multiple CPUs or multiple cores on one or more CPUs, e.g. an Intel Core 2 Duo computer.

On Unix, ACBLmerge 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.

   J	→	1	M	→	4	P	→	7
   K	→	2	N	→	5	Q	→	8
   L	→	3	O	→	6	R	→	9

   The images may be any size and do not all need to 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, or other image adjustments.

   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.

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 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.

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 on non-Windows platforms, 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.

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