|
|
Yacht Report Perl Script |
If you are reading this page and don't understand what it is about, then
don't panic. Normally the user will not see or need the data described
here. I have placed it as a web page so that I can access it whenever and
wherever I need to. If you are interested in using these scripts to
display yachting results then please contact me and I'll be pleased to help.
The Yacht Report Perl script is used to generate the result reports from the yacht results. The data is obtained from the results file and displayed to the user as an HTML page. This page gives instructions to use this script. Like many other scripts the input parameters are taken from the query string appended to the URL of the script. The query string defines the report that will be generated.
The script is located at : www.eastmore.biz/cgi-bin/YachtReport2001.pl Copies of the script may be running on other servers. Check with your system administrator. An older version of the scripts is available. The older version is prior to the changes introduced in the ISAF 2001 rule changes, this script is named YachtReport.pl. This is the preferred version to use. The older version has been left to support existing users and there is no guarantee that it will be maintained.
The results are stored in a CSV file. Normally the file is created automatically by the results software. It is possible to create the files manually as they are comma separated text files. One part that you may need to edit manually is the options line. This controls the number of discards and in the case of low scoring series the points awarded to DNS boats. The format of this line is as follows:
<OPTIONS>,DI,n,MI,n,CO,n,DN,x,TI,f
Where the numeric value of the parameter follows its two letter code. DI = Number of discards, after a minimum (MI) number of races. CO defines the number of races to count (system will calculate the required number of discards based on the races sailed). DI plus MI and CO are mutually exclusive, if both appear discard results are undefined! DN is the number of points awarded to a DNS boat. Where 'x' is T+n or S+n or n. Corresponding to the number of entrants in the series plus 'n' points, the number of starters plus 'n' points or fixed at 'n' points. Only applies to low scoring series (high scoring always score 0 for DNS), default is T+1. TI defines how a series tie break will be handled. Where 'f' may be one of 'full' (default) and meaning the full ISAF Appendix A rules (2000 to June 2002), '2002' for the ISAF Appendix A after the July 2002 changes, or '8.3' meaning just using rule 8.3 (last race) from Appendix A.
Parameters may appear in any order and each pair is optional, however MI makes no sense without DI. Defaults, DI=0 and MI=0.
The race result header line, i.e. the <PLACES> row contains the following fields:
- The event title
- The long format of the race name
- The short form of the race name
- The long form of the class name
- The short form of the class name
- Status of the race
0 = Race not yet started
1 = Race in progress (not all results included)
2 = Race abandoned
3 = Race complete- The time the race was started (time format)
- The date the results were created (date format)
- The time the results were created (time format)
- Handicap type for this class
0 = Level Rating
1 = TMF (primary class)
2 = TMF (secondary class)
3 = CYCA Minutes in an hour
4 = Channel handicap (depreciated, use TMF)
5 = IMS (no longer supported)
6 = RYA Portsmouth Yardstick Number- Hidden Results flag
0 = Results are included in series total and points displayed
1 = Results excluded from series total, no points displayed- Points Weighting - Assumed to be zero if omitted or empty, otherwise this number of points is added to the DNS points (after calculated in the normal way).
The full definition is contained in a word document (CSV File Format Specification) - ask if you need it.
The command line defines the data file and type of the report that will be generated. The full URL of the page required will be defined as :
<url>?<tag>=<parameter>{&<tag>=<parameter>}
Where
<url> is the URL given above.
<tag> is one of the tag listed in the table below.
<parameter> is the value associated with this tag value.
{ } indicates this is repeated zero or more timesCommand Line Parameters
| Tag | Description |
|---|---|
| file | Defines the name of the file that the results are extracted from. Normally this file will contain all the information about one series of races. This parameter is mandatory (except for the detail report - see below). |
| type | Defines the type of the report. See the table below. |
| class | Short name of the yacht class for the report to be printed. 'series' is valid for the overall series report. 'all' and 'allbyclass' are valid for the entrant reports. |
| race | Defines the race name for the report. Set this parameter to 'Series' to get a overall series report. |
| yacht | Sail number of the yacht. Only required when printing the yacht's individual report. If the sail number contains a space then this must be replaced by a %20 sequence. |
| lines | By default all the yachts in the report will be printed. If only the top 'n' places are required, the use this parameter. For example lines=5 will give the top 5 positions only. |
| order | Defines the order that the entrant reports are to be sorted in. The valid options are 'alpha' and 'num'. 'Alpha' orders alphabetically by the yachts name. 'Num' order numerically on the sail number. |
| debug | Prints additional information if this parameter is included in the command line. Add "&debug=1" to the URL to switch on. This parameter is not usually included in the URL. Add it manually if you are having difficult with a page. |
Report Types
The type name is case sensitive and the full name must be included.
| Type | Description |
|---|---|
| result | Displays the results of a particular race in the series. The class and race parameters must be present. |
| yacht | Displays all the results in the series for the indicated yacht. This type of report requires the 'yacht' parameter to be defined. |
| search | Displays the search for a yacht page. Allows the use to enter the details of a database search. Use this version to get the query form. |
| name | Performs the search for a yacht. Usually used in
response to a 'search' report. This report type requires both the
'yacht' and 'race' parameters to be set. 'yacht' defines the data
to be matched, 'race' defines the field to be searched (1 = Sail number, 2 = Yacht's name, 3 = Owner's name, 4 = Club). |
| details | If used with a file name then a diagnostics report about that file is printed. If used without a file name then a scan of the site is done and a list of all results files returned. Assumes that results files are in the CGI directory or a sub-directory thereof. |
| entrant | Get a list of the entrant details based on the information in the results file. |
The configuration file uses the same name as the results file but with an extension of '.cfg'. This file may contain one or more lines. Each line defines one parameter. The tag and the parameter value are separated by a comma ','. Thus each line can be defined as :
<tag>,[<parameter>].
If the tag appears more than once in the file the last definition will be used. The tag name is not case sensitive. However you should note that the when the parameter defines a filename this will often be case sensitive. The comma must be present even if no parameter is needed.
| Tag | Description |
|---|---|
| background |
Allow the background image to be defined. If omitted a plain white background is used. If used this defines a filename. The file path is relative the page being displayed. |
| header | Defines the name of the file that includes the HTML text that will be included at the top of the page. The file name is relative to the directory containing the YachtReport script. |
| footer | Defines the name of the file that includes the HTML text that will be included at the bottom of the page. The file name is relative to the directory containing the YachtReport script. |
| owner | This parameter does not require a parameter. If present it will cause the reports to be generated with the owner rather than the yachts name as the key identifier field in both series and places reports. More useful for dinghy race results; traditionally the helm's name is used in this case. |
| name | The report header name that will be used above the Yacht's Name field. Defining this field automatically adds the Yacht's Name field to the places report. In dinghy results this will normally contain the type of boat, and some the title should be set to 'Type'. |
| series | This parameter takes a paramter indicating the columns to be printed in the series report. The parameter may be one of 'name' (include yacht's name) or 'owner' (to include owner's name) or 'both'. For backward compatibility this parameter can be supplied without a parameter - this defaults to 'both'. |
| level | Controls the information that will be displayed for a level rating class in the reports. Parameter can be one of 'handicap' to display the yacht's handicap, 'corrected' to include the corrected time, or 'both' to include both of these fields. Omit this parameter to suppress these fields. |
| hr | Allows the user to define a image file that will be used in place of the horizontal ruler at the top and bottom of the page. The file path is relative the current page. |
| key | Defines additional entries to for the results finishing codes. Typically used to add a description for non-standard codes such as OOD, RSQ etc. |
| image_index | Defines a list of image index files. These are the XML formatted files. Multiple files may be listed separated by a ';'. File names are relative to the script directory. |
These tags are depreciated and may not work with the 2001 version of the script. They may be used with the older version of the script, please don't use them for new work.
| Tag | Description |
|---|---|
| image_dir | The directory path to where the pictures of the yachts are stored. Filename must match the sail number of the yacht (in the same format as that yacht's sail number appears in the results). All files are a .jpg extension. |
| image_name | Name of the text file containing the list of files in the image directory. File needed because the script does not have permission to scan the image directory. |
| image_lower | This does not require a parameter. If present it will force the yacht image file names to lower case. |
The header and footer files are simply HTML text files that are copied verbatim into the page that is being generated. The contents of the header file are placed after the start of the page body (<body>). By default, the contents are left aligned on the page (YachtReport.pl defaults to centered on the page). The contents of the footer file are included immediately prior to the closing body tag (</body>).
|
Copyright © Phil Walter 2001-2009 |