Scratch Bot

Scratch Bot Help Doc

Author: Jeff Platt

Last updated 11/13/2010

General Overview

Scratch Bot enables JCapper users to import scratches and races taken off the turf in real time right from the internet. All you need is a live internet connection. Scratch Bot works by searching the internet for scratches and race changes and parsing the web pages that it finds. Whenever Scratch Bot finds a horse listed as a scratch, Scratch Bot will process the horse as a fresh scratch and notify the user with a message box. Whenever Scratch Bot finds a race that has been taken of the turf, Scratch Bot will make the surface change and notify the user with a message box. Scratch Bot is a wonderful tool. But a word of warning is in order. Scratch Bot is only as good as the info found on the web pages that it parses. If a horse is scratched but not listed as a scratch on any of the web pages it parses, then obviously Scratch Bot won’t be able to scratch the horse. If a race is taken off the turf but the track for whatever reason doesn’t update the information in the right way to the proper web data sources, again, Scratch Bot won’t be able to recognize the race as having been taken off the turf and won’t be able to do its job correctly.

Based on user feedback so far, the overall experience with Scratch Bot has been good to excellent. Most tracks do make every effort to get their web pages updated in real time. Incorrect info posted on track web pages has actually become quite rare. But mistakes by the tracks do happen occasionally.

Section I – Parsing the XML --

In October, 2009 Equibase introduced a new system called Scratches and Changes Today. The idea behind that system was to create a single source on the web where players could go to get accurate scratches and changes info constantly updated in something approximating real time. Very early on it was decided that XML was the perfect delivery vehicle for getting scratches and changes propagated out onto the web pages at Equibase.com as well as the web pages of individual tracks and ADWs.

The Equibase XML Feed -

The Equibase XML Feed is at the core of the Scratches and Changes Today system. Scratches and changes from every North American track are constantly updated to the XML feed throughout the day – often, within a minute or two of when they are first announced by the track announcer over the public address system.

It’s all in the timing -

Before moving on to the Scratch Bot tutorial I’d like to go over just a few of the things you should be on the lookout for. Knowing ahead of time when scratches and changes are updated on the web is crucial to you getting the most out of Scratch Bot.

Here’s a rundown of how and when scratches and changes are updated to the XML Feed:

Early Scratches and Changes – Sometime between 60 and 10 minutes prior to post time for race one, keep in mind this time frame varies from one track to another depending on how well organized they are and their commitment to making the system work, a track employee will log into the Equibase system and key in the early scratches and changes. As soon as the track employee hits the submit button, individual scratches and changes are propagated to the XML and subsequently out onto the Scratches and Changes Today web pages and RSS Feed available at Equibase.com. Further, individual scratches and changes are also propagated onto those individual track and/or ADW web pages that use the Equibase XML as a data source for reporting their scratches and changes to players.
Subsequent Scratches and Changes – Sometime between 45 and 10 minutes prior to post time for race one, again this time frame varies from one track to another depending, the Equibase chart caller shows up for work and takes over responsibility for keying scratches and changes into the Equibase system. Because the chart caller has to key scratches and changes into the system anyway before he or she can cut a chart, it was decided (by Equibase CEO Hank Zeitlin) to make it the chart caller’s job responsibility to key subsequent scratches and changes into the system earlier (as soon as they become available) rather than later (after the race had been run.)

Note: An analysis of the previous system and where it was most frequently breaking down clearly showed that in almost all cases, missing and/or incorrect scratches and changes info was coming directly from the track employee level.

Relying on the Equibase chart caller rather than track employees to key in scratches and changes info was one of the keys to making the system work as designed.

Understanding how and when scratches and changes info becomes available in the XML is of paramount importance when it comes to getting the most out of Scratch Bot.

Parsing the XML (How To)

Parsing the XML is easy. Here are the steps:

On the Main Module click the button labeled Scratch Bot. This will launch Scratch Bot.
On the Scratch Bot Module, click the XML button. This will cause Scratch Bot to Clear Scratches and parse the Equibase XML Feed for new scratches and changes. After the XML has been parsed, the user will be presented with a message box showing races taken off the turf followed by a message box showing the total number of scratches found in the XML. After clicking OK through both message boxes, at this point (in about 99% of all cases) complete current scratches and changes will have been imported into the program. To see the effect of current scratches and changes on user reports, all you have to do at this point is x-out of Scratch Bot, run a Calc Races routine, and launch the Report Viewer.

Note: Clicking the XML Button clears existing scratches from the Scratches.txt file.

Using Scratch Bot as a Web Browser - the Plus “+” Button

Scratch Bot contains an embedded Internet Explorer web browser. To have Scratch Bot display web content currently being browsed, click the Plus “+” button. This will cause Scratch Bot’s interface to expand. A viewing window will appear and web content currently being browsed will display in that window. Clicking the Minus “-“ button causes the window to disappear and Scratch Bot’s interface to return to its normal default state.

Note: In addition to Scratch Bot, this same Plus “+” button, viewing window, and Minus “-“ button interface can also be found in other JCapper modules such as the Live Play Module and the File Download Tool found in JCapper’s HDW File Manager.

Note: I purposely did not include an address bar in Scratch Bot’s interface. I did this for security reasons. Scratch Bot’s Plus “+” button, Viewing Window, and Minus “-“ button interface was designed more along the lines of letting you see web content the module is currently parsing than with the idea that you would want to use Scratch Bot as a stand alone web browser. If you are going to surf unknown pages across web, please use a web browser intended for that purpose. When you browse web content using Scratch Bot you are visiting known pages at known sites which minimizes (but does not eliminate) your chances of picking up trojans, viruses, or other pieces of malicious code.

Note: The short list of sites that I am personally willing to use Scratch Bot as a stand alone app to surf would be: The Equibase XML Feed, Brisnet SuperTote, and the data download area at Handicappers Data Warehouse (HDW.) For example, I am perfectly willing to use the Scratch Bot “+” button to navigate the Equibase XML or visit the Brisnet site to start a new session so that I can get a Brisnet session cookie placed on my local machine. I would not, however, want to use Scratch Bot to browse other third party sites that I am unfamiliar with. I hope that makes sense.

Required Settings for Scratch BOT Operation

In this section I will cover those JCapper user settings that Scratch Bot relies on for its operation.

TrackAbbreviations Table

Scratch Bot uses data stored in the TrackAbbreviations Table of the c:\2004\JCapper.mdb file when parsing the Equibase XML Feed.

IMPORTANT: Before Scratch Bot will be able to parse the XML for scratches and changes, the following three entries must be present in the TrackAbbreviations Table for each track you wish to have Scratch Bot process for you when you click the XML button:

FileAbbrev Field

Key the first three characters of the data file name for the individual track into this field.

ToteAbbrev Field

Key the first three characters of the data file name for the individual track into this field.

Notes Field

Key the full track name found in the track_name attribute as listed in the XML itself into this field.

Hint: After clicking the XML button, click the Plus “+” button to display the complete XML in the Display Window. The XML itself is clickable. Clicking the minus sign “-“ or dash character to the left of each track node in the XML will collapse the XML for that individual track. Clicking the “+” or plus character to the left of a collapsed track node in the XML will expand the XML for that individual track. Expanding the XML for each track will make nodes containing track_name attribute tags visible. Use the track name as listed in the track_name attribute tags for each track.

Note: Although there may be multiple track_name attribute tags listed in the xml for each track, Scratch BOT requires a single entry for each track (which includes data for each of the three fields listed above) in order to be able to read and process changes from the XML for a given track.

Example: Suppose for the sake of argument that you want to create a set of table entries for Delaware. First, click the XML button. Next, click the Plus “+” button to display the XML. Then, collapse the XML for individual tracks by clicking the minus character immediately to the left of the track names in the xml for individual tracks until the xml for Delaware becomes visible. When the xml for Delaware becomes visible, notice that the track_name attribute reads “Delaware Park” – You would key “Delaware Park” (without the quote characters) into the Notes field of the TrackAbbreviations table.

The Track Abbrev Table Button

The Track Abbrev Table Button is located in the bottom left area of the Scratch Bot screen. Clicking the Track Abbrev Table Button will launch the TrackAbbreviations Table Interface – enabling you to make TrackAbbreviations Table entries so that you can set up individual tracks in Scratch Bot.

Instructions for Using the TrackAbbreviations Table Interface

The TrackAbbreviations Table Interface behaves in a way that is very similar to a spreadsheet. Making entries is easy. Simply click inside of the cell where you want to enter data and key in the data that you want to enter. There is no Save button. To persist data sitting in a cell to the table, simply navigate (with a mouse click or by hitting the tab key on your keyboard) to a different cell. The data in the cell that you just navigated away from will appear to “jump” slightly. As soon as you see the data “jump” it will have been written to the table.

Adding a New Row

To add a new row using the TrackAbbreviations Table Interface, first launch the TrackAbbreviations Table Interface by clicking the Track Abbrev Table button. Then scroll or tab all the way to the bottom until the very bottom row in the interface becomes visible. Hint: The very bottom row in the interface will be indicated by the presence of a Star/Asterisk “*” character in the box located at the left hand edge of the row. Click inside of a cell in the bottom row, key your data into that cell, and navigate to the next cell with a mouse click or by using the tab key. When data has been persisted in all three fields (TrackAbbrev, ToteAbbrev, and Notes) your new entry will be complete.

Deleting an Existing Row

To delete an existing row using the TrackAbbreviations Table Interface, first launch the TrackAbbreviations Table Interface by clicking the Track Abbrev Table button. Scroll or tab vertically through the table until the row you wish to delete becomes visible. Highlight the row you wish to delete by single clicking the box at the left hand edge of that row. Finally, with the row highlighted, tap the Delete key on your keyboard once. The row will disappear – indicating that data for that row has been deleted from the table.

A Word of Warning: When you delete a row using this interface, you will not be presented with a warning/confirmation message prior to deleting a highlighted row from the table. As soon as you tap the Delete key, the interface will delete the highlighted row from the table.

Editing Data in an Existing Row

To edit data in an existing row using the TrackAbbreviations Table Interface, first launch the TrackAbbreviations Table Interface by clicking the Track Abbrev Table button. Scroll or tab vertically through the table until the row you wish to edit becomes visible.

Click inside of a cell in the row you wish to edit, key your data into that cell, and navigate to the next cell with a mouse click or by hitting the tab key. When data has been persisted in all three fields (TrackAbbrev, ToteAbbrev, and Notes) your edit will be complete.

Note: Alternately you can use a third party database app such as Microsoft Access to open the c:\2004 JCapper.mdb file and edit data in the TrackAbbreviations Table.

Exceptions – Handling the Ampersand “&” Character:

For some reason there are a handful of tracks that insist on making an ampersand “&” character part of their own track name in the Equibase XML. This is problematic because the ampersand character is part of the SQL command set. Using the ampersand character as part of the track name has the ability to wreak havoc with SQL expressions attempting to read such track names from tables.

I have created an internal work around to enable Scratch Bot to handle track such track names. As of this writing there have been only two track names using the ampersand character as part of the track name in the Equibase XML: Charles Town and Mountaineer.

The valid Notes field entry, despite what appears in the xml, for Charles Town is simply “Charles Town” (without the quote characters.)

The valid Notes field entry, despite what appears in the xml, for Mountaineer is simply “Mountaineer” (without the quote characters.)

Note: Be aware that tracks sometimes change their names. For that reason, track names as listed in the track_name attribute in the xml are subject to change. If and when a track changes its name in the xml, it is your job to pull up the TrackAbbreviations Table Interface and edit the Notes Field for that track.

Enhanced Settings Module – Scratch Bot Parse Type Setting

There is one Scratch Bot setting in the Enhanced Settings Module. Here is a cut and paste of the description of this setting from the Enhanced Settings Module Help Doc:

Scratch BOT Setting

Element Type: Drop Down

Purpose: Controls the type of parse routine used by Scratch BOT when the XML Button is clicked.

Options:

0 All Scratches in the XML – When this option is selected, Scratch BOT parses the entire xml stream at once.
1 Scratches For Loaded Card Files Only – When this option is selected, Scratch BOT parses the xml stream one track at a time and only for the track codes currently loaded into JCapper.

Importing Default Settings (Master Track List) Into the TrackAbbreviations Table

Default settings (also known as the Master Track List) for the TrackAbbreviations Table were compiled in late summer 2010 and are included in the TrackAbbreviations Table in the JCapper.mdb file placed on the c:\JCapperBuild folder during a program install.

To import the default settings from the c:\JCapperBuild\JCapper.mdb file into the active c:\2004\JCapper.mdb file so that the Master Track List will become available to Scratch Bot when parsing the XML:

Click the Import Master Track List button located on the lower right hand area of the Scratch Bot screen and answer Yes at the prompts.

Logic within Scratch Bot will import the Master Track List (default entries for all North American tracks) from the TrackAbbreviations Table found in the c:\JCapperBuild\JCapper.mdb file into the same table in the c:\2004\JCapper.mdb file. After the import routine is complete, you will find that your previous TrackAbbreviations Table entries will have been overwritten with new entries from the master track list.

The Scratches.txt file

This is not a setting per se but you need to know about this file. The Scratches.txt file sits on your current Default Data Folder and contains all current scratches. You can view this file in Notepad (or other text editor) by navigating to your current Default Data Folder, finding the file, and opening it with a double click. Keep in mind that opening this file using a third party app may place a “lock” on this file. When the file is “locked” you will be unable to run a Calc Races routine. To clear an existing “lock” on this file, simply close down whatever third party app you are using to view this file.

The Clear Scratches Button
To Clear Scratches, simply click the Clear Scratches button and answer Yes at the prompt. Doing this causes JCapper to overwrite the existing Scratches.txt file with a fresh blank file.

Important Note: As a Best Practice, I strongly recommended that you get in the habit of clearing out the previous day's scratches (before getting scratches for each new race day) at the start of each new race day. Why? Clearing Scratches prevents thousands of scratches from accumulating in the Scratches.txt file. You can use any of the following modules to clear scratches: Card Loader, File Downloader, Scratch Parser, Manual Changes Module, or Scratch Bot.

Troubleshooting

Note about Clearing Scratches: If you ever notice that ALL scratched horses still appear on your HTML Report, Text Report, or JCapper Past Performances no matter how you picked the scratches up in the first place - the FIRST thing you should try is Clearing Scratches. Follow that up with picking up the scratches again followed by running a Calc Races routine. In about 99.9 percent of all cases that will correct the problem.

Note about timing of WHEN scratches and changes data is made available: Make sure to READ and UNDERSTAND the section above titled “It’s All in the Timing.” If you notice that Scratches and Changes are being picked up from the XML for some tracks but not all – The FIRST thing you should suspect is that scratches and changes for the missing tracks are missing because the info has not yet been posted to the xml. Your best course of action is to use Scratch BOT as a web browser and verify this (visually) for yourself. Click the “+” Button and navigate through the individual track nodes in the XML itself. Once you learn to do this, it will become apparent at a glance whether or not individual tracks are either present or are missing from the xml.

Note about changes of track names in the XML: Please be aware that, for whatever reason, individual tracks will sometimes request to have their track names changed in the Equibase system. When that happens it is your job to change the track name in the Notes Field of the TrackAbbreviations Table in order to enable Scratch BOT to be able to process scratches and changes found in the XML for that track. The first sign that a track name has changed in the xml will likely be that you notice Scratch BOT is no longer processing changes for that individual track.

If you notice that Scratches and Changes are being picked up from the XML for some tracks but not all – AND YOU HAVE VERIFIED THAT THE TRACKS IN QUESTION DO IN FACT HAVE CHANGES LISTED IN THE XML (meaning you are certain the problem is not related to the timing of when the changes are posted to the xml) - the FIRST thing you should check is an exact match between the track_name attribute in the XML vs. the track name persisted in the Notes Field of your TrackAbbreviations Table. In about 99.9 percent of all cases that I have looked into, editing the Notes Field of the TrackAbbreviations Table to match the track_name attribute of the XML will correct the problem.

Note about Cannot Initialize Data Bindings Error Message: If you get this error message when you click the Track Abbrev Table button, the FIRST thing you should suspect is that the DLLs required to operate the Microsoft Data Grid Control used by Scratch BOT (and other JCapper Modules) have not been (or are no longer) properly registered. The solution to this problem is to use a program called Regsvr32 to register the needed DLLs.

Here is a link to a JCapper Help Doc illustrating the general procedure:

http://www.jcapper.com/regsvr32.html

Once you understand the general procedure, this link will take you to a page where you can find information about registering the specific DLLs used by the Microsoft Data Grid Control:

http://www.jcapper.com/TechServ_Bind.html

Scratch Bot Video

In addition to this help doc, a Scratch Bot video is available. To watch the video, visit JCapper.com and click the link on the Nav Bar labeled JCapper 101 Audio/Video. Then click the Index item on the JCapper Podcasts page labeled Daily Reports. Then, look for and click Scratch Bot Video link to watch the video. If the server is too slow when loading the video file, right click the link to the video and select Save Target As. Save the .wmv file to your local machine and watch it from there by double clicking the .wmv file itself.

Note: What you will pick up from watching the video that is (for some) difficult to pick up from this Help Doc: The video shows me clicking and navigating inside of the XML itself so that track names in the track_name attribute of the xml become visible. If my description of how to do this within this Help Doc seems cloudy… Then watch the video!

Section II – Parsing Live Tote and Individual Track Links

Note: Prior to October, 2009 parsing Live Tote and Scratches Links for individual tracks was the preferred way of operating Scratch Bot. This functionality remains as part of Scratch BOT. User still using it will find that occasionally use of this functionality makes a good adjunct to parsing the XML. This is especially true with gate scratches.

Parsing Live Tote Links

Alternately, you can also parse Live Tote links for individual tracks loaded into JCapper (using the Card Loader or Screen Two of the File Downloader) as a source for scratches and changes info.

Here are the steps:

Use the Card Loader or Screen Two of the File Downloader to load one or more race card files into JCapper.
Start a new SuperTote session to get a Brisnet session cookie on your local machine. See the section below on Starting a New Session.
Launch Scratch Bot. When Scratch Bot is launched, the module displays a Live Tote Link for each loaded race card file.
Click the Live Tote Link for a loaded track or race card file. This will cause Scratch Bot to parse the live tote stream found at Brisnet SuperTote for that race card file. Horses found to have non numeric odds on the live tote stream for the current race are treated as fresh scratches and will be added to the list of scratched horses for that card. You will receive a message box for each such horse. After clicking OK through any such message boxes, at this point current scratches will have been imported into the program. Next, to see the effect of current scratches and changes on user reports, run a Calc Races routine and launch the Report Viewer.

Note: Clicking a live tote link does not clear existing scratches.

When and Why Live Tote Links are sometimes more up to date than the XML:

The chart caller can normally be expected to log into the Equibase system and key in fresh scratches as soon as it is reasonable and prudent for him to do so. However, in cases where the chart caller has already taken up a position to start calling the race (one or more horses are already in the gate) and a scratch occurs – in some racing jurisdictions (most notably New York) the gate crew will reload the field and send them on their way as quickly as possible. In such cases it is not reasonable to expect the chart caller to put down his binoculars to key in new scratches before the race goes off. In such cases the scratch will normally appear on the live tote stream (as indicated by non numeric odds) before the scratch appears in the XML.

In such cases you are better off parsing the Live Tote Link to pick up the scratch (or using the Manual Changes Module) than you are parsing the XML.

Scratches and Entries

Note: If a horse is scratched at the gate and that horse is part of an entry:

In New York the remaining part of the entry is scratched for wagering purposes and will run for purse money only.
In most other racing jurisdictions the remaining part of the entry remains a wagering entry. However, one weakness of the live tote stream is that the odds for separate parts of an entry are not displayed separately. In such cases you will NOT be able to pick up the scratch by Parsing the Live Tote Link. If the chart caller has time to key the scratch into the Equibase system you MAY be able to pick the scratch up by Parsing the XML.

Note: In almost all cases, your best means of picking up scratches when one part of an entry is scratched is to use the Manual Changes Module.

Starting a New Session (and dealing with those annoying Session Expired Messages)

Before diving into instructions for starting a session, it might be a good idea to first point out that starting a session is not required to parse the XML.

However, starting a session and getting a session cookie placed on your local machine is required prior to using Scratch Bot to parse the Live Tote Stream and Scratches Links for individual tracks at Brisnet.com.

If you get a “Session Expired” message when parsing a live tote link or an individual track link, that means that you do not have a valid session cookie on your machine. Your best course of action to get a session cookie placed on your machine would be to log into Supertote and start a new Session.

Scratch Bot contains an embedded Internet Explorer web browser. Each time you click on a live tote link or a track scratches link, the Internet Explorer web browser part of Scratch Bot visits web pages that present current live odds and scratches information. This behavior is no different than if you had an open instance of Internet Explorer running and used it manually to surf the same web pages. One link click in Scratch Bot equals one link click in Internet Explorer. Literally. When I first created Scratch Bot in early 2004, Bris didn’t care that apps like it might be browsing their live web pages. Since that time they have changed their tune and have implemented security measures designed to prevent unauthorized users from browsing their live odds pages. Their security measures involve having the page itself ask the user to log in using a valid username and password followed by having their server place a session cookie onto the user’s local machine. Their web pages are programmed to check for the presence of a session cookie. If one is found, the user is allowed to browse the current web page. If a session cookie is not found, of if it is found to have expired, the user is presented with a session expired message. The easiest best way to get the Bris server to place a session cookie placed on your local machine (which gives you subsequent rights to browse their pages) is to have a Bris account in good standing and log onto their site with your Brisnet user-name and password. Session cookies have a shelf life of a few hours. So after a few hours the cookie expires and you will have to log in all over again. When you get a Session Expired message in Scratch Bot it just means that there is no current session cookie present on your machine.

How to start a new session and get a new session cookie:

1. Open a separate instance of Internet Explorer (or use the built in browser found in Scratch Bot.)

2. Browse to the Bris Site and visit their Supertote page.

3. Log into Supertote using your Bris username and password. When you do this the Bris page will put a new session cookie on your machine.

4. Keep the current instance of Internet Explorer open during live play and keep it pointed at the Bris Supertote page. That way you will keep your session open.

So long as you have a current session cookie on your machine Brisnet will recognize you as authorized to browse live odds and scratches on their site.

Note: If you do not have a current Brisnet account, consider contacting Brisnet.com and signing up for an account there.

Note: Your Internet Explorer security settings must be such that you allow Bris to place the session cookie onto your machine upon login. Without a current session cookie, Scratch Bot will not be able to browse web pages at the Bris site.

Parsing Scratches Links

Alternately, you can also parse Scratches links for individual tracks loaded into JCapper (using the Card Loader or Screen Two of the File Downloader) as a source for scratches and changes info. Here are the steps:

Use the Card Loader or Screen Two of the File Downloader to load one or more race card files into JCapper.
Start a new SuperTote session to get a Brisnet session cookie on your local machine. See the section below on Starting a new SuperTote Session.
Launch Scratch Bot. When Scratch Bot is launched, the module displays a Scratches Link for each loaded race card file.
Click the Scratches Link for a loaded track or race card file. This will cause Scratch Bot to parse the scratches page found at Brisnet.com for that race card file. Horses listed as scratches on that web page not already listed in the Scratches.txt file on the current Default Data Folder are treated as fresh scratches and will be added to the list of scratched horses for that card. You will receive a message box for each such horse. In addition, Scratch Bot will evaluate the track condition listed for the turf course at that web page.
In the event that Brisnet has the track condition for the turf course listed as Turf: Off, Scratch Bot will assume that any turf races for that track are now off the turf and you will receive a message box that today’s turf races are now off the turf. After clicking OK through any such message boxes, at this point current scratches and changes will have been imported into the program. Next, to see the effect of current scratches and changes on user reports, run a Calc Races routine and launch the Report Viewer.

Note: Clicking a scratches link does not clear existing scratches.