Pedigree Website Package Instructions
   (updated to reflect version 4.7)
 
 

• FREQUENTLY ASKED QUESTIONS
• Package Contents
• Modifying the Package Files
• Uploading the files to your website
• Preparing your breeding records database
• Uploading the database
• TROUBLESHOOTING HELP
• Change log from version to version

Package Contents

How will I get the package?

Send an e-mail to me requesting the pedigree website package. I will e-mail back to you a URL to a Zip file containing the software.

How do I un-Zip the package?

Use the DOS program PKUNZIP or the Windows program WinZip.

I don't have these programs, where do I get them?

Get PKUNZIP at www.pkware.com. Get WinZip at www.winzip.com.

What is in the package?

A collection of files.

• Some of the files go in the "Document Root" (or a sub-directory) of your website:
• search.html -- The pedigree search page.
• background.jpg -- The image background for the search page.
• dogprofile.gif -- A representative image of your dog breed displayed on the search page.
• search.gif -- An image button allowing a new search to be started.
• step1.gif -- An image showing Step 1 of the search process.
• step2.gif -- An image showing Step 2 of the search process.
• step3.gif -- An image showing Step 3 of the search process.
• step4.gif -- An image showing Step 4 of the search process.
• step5.gif -- An image showing Step 5 of the search process.
• Some of the files go in the "cgi-bin" directory of your website:
• breeding.pl -- The CGI script that searches your database and prints breeding info.
• common.pl -- The CGI script that common functions for all the other CGI scripts.
• config.pl -- The CGI script that allows you to personalize the operation of all the other CGI scripts.
• entry.pl -- The CGI script that allows people to email you pedigree updates.
• geneal.pl -- The CGI script that searches your database and prints pedigrees (with links).
• logview.pl -- The CGI script that allows you to monitor usage of your database.
• logview_nodns.pl -- This script is the same as logview.pl, but it omits the reverse DNS lookups in the event your web server doesn't support them.
• palmbreeding.pl -- A version of the breeding info script that runs on Palm Pilots.  If you expect to use this, you will also need to contact me to arrange for the creation of a "PQA" file.
• pedigree.pl -- The CGI script that searches your database and prints pedigrees (without links).
• reverse.pl -- The CGI script that prints reverse pedigrees.
• security.pl -- The CGI script that allows you to control database access with passwords.
• trial.pl -- The CGI script that searches your database and allows you to print trial pedigrees.
• wapbreeding.pl -- A version of the breeding info script that runs on Wireless Internet cell phones.
• Some of the files usually go in the "cgi-bin" directory of your website:
• mybreed.dbw -- A sample pedigree records database.
• mybreed.ixw -- An index file for the sample pedigree records database.
• mybreed.brw -- A sample breeding info records database.
• mybreed.bxw -- An index file for the sample breeding info records database.
• mybreed.kxw -- An index file allowing fast search of the sample breeding info records database.

Modifying the Package Files

Which files do I need to modify?

You must modify search.html and config.pl. You may (and should) modify background.jpg and dogprofile.gif to customize the appearance of your website.

What do I use to modify them?

You need to use a text editor, like Microsoft Notepad or Wordpad. Do not use a word processor, like Microsoft Word. I also strongly recommend that you do not use a Web Page Editor such as Microsoft FrontPage or Claris HomePage. If you want to use a fancy commercial editor, I recommend TextPad.

What do I have to change in "search.html"?

There are a number of items to change:

• Change the name of your breed in between the title and /title tags.
• If you change the name or path to your search page background image to something other than "/background.jpg", change the URL in the body background= tag.
• If you change the name or path to your breed's representative picture to something other than "/dogprofile.gif", change the URL in the img src= tag on the line just below the body background= line.
• Change the name of your breed between the h1 and /h1 tags.
• Change the name of the sponsor on the Internet service provided by line.
• Change the name of your breed between the h3 and /h3 tags.
• If you change the name or path to the CGI script to something other than "/cgi-bin/geneal.pl", change the URL in the form action= tag.
• In the Select which database to use section, put the name of your database.
• Update the Page created by and Changes last made on lines near the bottom of the file.

What do I have to change in "config.pl"?

There are a number of settings that you can modify:

• $szBreed -- Put the name of your breed of dog in between the quotes.
• $szDatabase -- Put the filename of your database in between the quotes. The convention we have been following so far is to name the database your-breed.dbw, where you substitute your-breed with the actual name of your breed. For example, if your breed is Akitas, you would enter "akita.dbw". I recommend that you always use all-lower-case spellings for your filenames.
• $szSponsor -- Put your name, or your kennel name in between the quotes.
• $szHtmlSearch -- Enter the full URL to your "search.html" search page.
• $szSponsorEmail -- Put your email address in between the quotes. Note that you have to put a backslash character in front of the at-sign in your email address. This is due to rules of the Perl language.
• $szSponsorSite -- Put the full URL to your website in between the quotes.
• $nDefaultGens -- Enter the default number of generations you want displayed in pedigrees in between the quotes. With this software, the number of generations includes the animal you are printing the pedigree for as generation number 1.
• $nMaxGens -- Enter the maxiumum number of generations you want to allow to be displayed in pedigrees in between the quotes. Beyond a certain limit, the pedigrees just aren't viewable on the screen or printable in a practical manner.
• $nMaxHitsDisplayed -- Enter the maxiumum number of search matches you want to allow to be displayed on one page in between the quotes. Some web servers will "time out" if you allow people to match too many entries, for example, if they ask for all animals whose names contain the letter "A". If this is happening to you, you can reduce the maximum hits allowed to prevent these "time outs" from happening.
• $nMaxWapHitsDisplayed -- Enter the maxiumum number of search matches you want to allow to be displayed on one page in between the quotes. Some web servers will "time out" if you allow people to match too many entries, for example, if they ask for all animals whose names contain the letter "A". If this is happening to you, you can reduce the maximum hits allowed to prevent these "time outs" from happening.  Also, WAP-enabled cell phones typically have very small screens, so this should be a small number.
• $nMaxPalmHitsDisplayed -- Enter the maxiumum number of search matches you want to allow to be displayed on one page in between the quotes. Some web servers will "time out" if you allow people to match too many entries, for example, if they ask for all animals whose names contain the letter "A". If this is happening to you, you can reduce the maximum hits allowed to prevent these "time outs" from happening.  Also, Palm Pilots typically have small screens, so this should be a modest number.
• $szSponsorCredits-- You shouldn't need to change this entry, it will be taken care of automatically due to the other settings you have made.
• $szCgiBreeding -- Enter the full URL to the "breeding.pl" breeding info CGI script.
• $szCgiGeneal -- Enter the full URL to the "geneal.pl" pedigree CGI script.
• $szCgiPedigree -- Enter the full URL to the "pedigree.pl" pedigree CGI script.
• $szCgiTrial -- Enter the full URL to the "trial.pl" trial pedigree CGI script.
• $szCgiReverse -- Enter the full URL to the "reverse.pl" pedigree CGI script.
• $szCgiEntry -- Enter the full URL to the "entry.pl" pedigree update CGI script.
• $szCgiSecurity -- Enter the full URL to the "security.pl" pedigree CGI script.
• $szCgiLogview -- Enter the full URL to the "logview.pl" or "logview_nodns.pl" pedigree CGI script (depending upon which you have chosen to use).
• $szCgiWapPhone -- Enter the full URL to the "wapbreeding.pl" breeding info CGI script for Wireless Internet cell phones.
• $szCgiPalmPilot -- Enter the full URL to the "palmbreeding.pl" breeding info CGI script for Palm Pilots.
• $szImageDir -- Enter the full URL to the directory where you will store all the image files ("search.gif", "dogprofile.gif", "step1.gif" through "step5.gif", etc.). This allows you to put them in a directory other than the Document Root if you want to.
• $szPhotoDir -- Enter the full URL to the directory where you will store all your animal photo files. This allows you to put only the filenames of the photos in your database if you want to. The Photo Directory will be prepended onto every filename to create the full URL when the scripts run. Alternatively, if you intend to enter the full URL of every photo into your database (which you would do if you intend to reference photos on the websites of your fellow breeders), then leave $szPhotoDir empty.
• $szImageBackground -- Leave this as "background.jpg" unless you change the filename of your pages' background image. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageDogProfile -- Leave this as "dogprofile.gif" unless you change the filename of your search pages' representative picture of your breed. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageStep1 -- Leave this as "step1.gif" unless you change the filename of the "Step 1" image file. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageStep2 -- Leave this as "step2.gif" unless you change the filename of the "Step 2" image file. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageStep3 -- Leave this as "step3.gif" unless you change the filename of the "Step 3" image file. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageStep4 -- Leave this as "step4.gif" unless you change the filename of the "Step 4" image file. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageStep5 -- Leave this as "step5.gif" unless you change the filename of the "Step 5" image file. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szImageSearch -- Leave this as "search.gif" unless you change the filename of the "Search" button image file. Note that the software generates the full URL to this image by prepending $szImageDir, mentioned above.
• $szFont -- If you want to change the default font displayed, you can enter the HTML here. Be sure to backslash any inner quotation marks.
• $szFontRed -- If you want to change the way (color, font) that titles and awards are displayed, you can enter the HTML here. Be sure to backslash any inner quotation marks.
• $szFontBlack -- If you want to change the way (color, font) that most of the text (animal's name, birth, etc.) are displayed, you can enter the HTML here. Be sure to backslash any inner quotation marks.
• $szFontSmall -- If you want to change the way (color, font) that the miniature hyperlinks (PICTURE, PEDIGREE, BREEDING INFO, etc.) are displayed, you can enter the HTML here. Be sure to backslash any inner quotation marks.
• $szTable -- If you want to change the way (border color, border width, cell padding, etc.) that the tables are displayed, you can enter the HTML here. Be sure to backslash any inner quotation marks.
• $szTableCell1 -- If you want to change the way (e.g., background color) that the table cells are displayed, you can enter the HTML attributes only here. Note that there are two table cell descriptions (see $szTableCell2 below). You can set both cells to look the same, or to be different. Be sure to backslash any inner quotation marks.
• $szTableCell2 -- If you want to change the way (e.g., background color) that the table cells are displayed, you can enter the HTML attributes only here. Note that there are two table cell descriptions (see $szTableCell1 above). You can set both cells to look the same, or to be different. Be sure to backslash any inner quotation marks.
• $nLogFlag -- If you want to log all accesses by web surfers to your database, set this to a non-zero value. Using a value of zero will turn off logging. For logging to work, you must also create a "log" subdirectory. This is described in more detail below in the Uploading the files to your website section.
• $nSecurity -- If you want to require login/password for every user who searches your database, set this to a 1.  If you want your database searches to be open to the public, set this to a 0.
• $nAllSiblingsFlag -- If you want all animals of the same parents to be considered "siblings", set this to a 1. If you only want animals from the same litter to be considered "siblings", set this to a 0.  If you want both siblings and half-siblings to be displayed, set this to a 2.
• $nBreedingShowParents -- If you want "breeding.pl" to show the parents underneath each and every animal's name, set this to a 1.  If you think that makes too much clutter, set this to a 0.
• $szAdminUsername -- User name you want to use when authenticating with the log viewer (logview.pl or logview_nodns.pl).
• $szAdminPassword -- Password you want to use when authenticating with the log viewer (logview.pl or logview_nodns.pl).

What exactly is a URL?

A URL is a Uniform Resource Locator. It is the "address" which tells your web browser how to find documents or images on the Internet. A URL consists of a "protocol" used to fetch the document or image (this is almost always "http:"), the name of the computer where the document or image resides (e.g., "//www.alfirin.net"), followed by the directory on the computer where the document or image is stored (e.g., "/images/"), followed finally by the filename of the document or image (e.g., "dogprofile.gif"). All together this looks like "http://www.alfirin.net/images/dogprofile.gif".

What is my Document Root?

A Document Root is the "top" directory of your web site that can be viewed by people using a web browser. In many cases, when you FTP to your web server, the Document Root is the directory you "land in" first. But in other cases, your Document Root may actually be a subdirectory of your FTP root. This subdirectory may be named "htdocs", "docs", "web", "www", "public_files", "public_html", or something similar.

How do I know what is the full URL of my Document Root?

You must be informed by your ISP what is the full URL of your Document Root. Typically you get an email from your ISP explaining this. Sometimes your ISP's website will explain how the full URL is assigned to you. If you have registered your own domain name, typically your document root will be something like http://www.your-domain.com/. For example, my domain is alfirin.net and my document root is http://www.alfirin.net/. If you do not have your own domain name, but you have a user ID at some ISP, your document root will typically be something like http://www.some-isp.com/~user-id/. For example, before I got my domain name, my user ID at Earthlink was "alfirin" and my document root was http://www.earthlink.net/~alfirin/. In some cases, ISPs don't include the "tilde" character.

What is my "cgi-bin"?

A "cgi-bin" is the directory of your web site that CGI scripts are allowed to run in. Almost always this directory is named "cgi-bin" and is a subdirectory of your FTP root. Occasionally this subdirectory may be named "cgi" or "cgi-userid" where userid is your login ID. For example, if my login ID was "alfirin" my ISP might name my cgi-bin directory to be "cgi-alfirin".

How do I know what is the full URL of my "cgi-bin"?

You must be informed by your ISP what is the full URL of your cgi-bin. Typically you get an email from your ISP explaining this. Sometimes your ISP's website will explain how the full URL is assigned to you. Almost always the URL will simply be the URL of your Document Root with "/cgi-bin" appended. But in a few cases, ISP's run CGI scripts on a completely different web server, so the full URL might be something like "http://cgi.alfirin.net/" when your Document Root was "http://www.alfirin.net/". In my case, the URL of my cgi-bin at Earthlink is http://www.alfirin.net/cgi/.

How do I use a different background and dog profile image?

Either find images you like on the Internet, or take your own pictures.

How can I get my own pictures onto the computer?

You can take a photo with a conventional camera, and have the prints developed as normal. You can use a flat-bed scanner or a photo scanner to load the picture into your computer. If you don't own a scanner, some film developing companies will scan for you, and provide you the picture on a floppy disk or on CD-ROM. Examples of such companies are:

• LazerQuick www.lazerquick.com.
• Seattle Filmworks www.filmworks.com.

Another technique you can use is to take the pictures with a digital camera. Then your photos can be loaded into your computer either with an e-film reader, or by using the link cable that came with the camera.

Uploading the files to your website

How do I get these files up to my website?

You can use FTP, WS_FTP, CuteFTP, or Microsoft Front Page.

How do I know if I have any of those programs?

Most operating systems come with an FTP program (Windows does). You have to buy WS_FTP, CuteFTP, or Microsoft Front Page separately. WS_FTP and CuteFTP have free trial periods, so you can try them out before you decide which one to buy.

My ISP's web site has a "file manager" web page for transferring files. Why can't I use that?

Such pages usually transfer all files in "Binary" mode. This damages the files that must be transferred in "Ascii" mode, and will make the pedigree scripts operate incorrectly.

How do I get WS_FTP?

Visit Ipswitch, Inc. on the Internet at www.ipswitch.com. You can buy WS_FTP online using your credit card.

How do I get CuteFTP?

Visit GlobalSCAPE on the Internet at www.cuteftp.com. You can buy CuteFTP online using your credit card.

How do I get Microsoft Front Page?

It is sold in stores carrying computer software, such as Office Depot, Office Max, and Fry's Electronics.

OK, I've got one of those programs, now how do I do the uploads?

You should upload the files as follows:

• search.html -- Put in your Document Root directory, upload in ASCII mode.
• background.jpg -- Put in your Images directory, upload in BINARY mode.
• dogprofile.gif -- Put in your Images directory, upload in BINARY mode.
• search.gif -- Put in your Images directory, upload in BINARY mode.
• step1.gif -- Put in your Images directory, upload in BINARY mode.
• step2.gif -- Put in your Images directory, upload in BINARY mode.
• step3.gif -- Put in your Images directory, upload in BINARY mode.
• step4.gif -- Put in your Images directory, upload in BINARY mode.
• step5.gif -- Put in your Images directory, upload in BINARY mode.
• breeding.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• common.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• config.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• entry.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• geneal.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• logview.pl (or logview_nodns.pl) -- Put in your cgi-bin directory, upload in ASCII mode.
• palmbreeding.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• pedigree.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• reverse.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• security.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• trial.pl -- Put in your cgi-bin directory, upload in ASCII mode.
• wapbreeding.pl -- Put in your cgi-bin directory, upload in ASCII mode.

The steps you use to upload these files using the different programs is:

• FTP --
  • Run the command ftp www.your-website.com from an MS-DOS window.
  • Enter your administrative username and password when asked.
  • Enter the command cd htdocs to view the Document Root directory or cd cgi-bin to view the cgi-bin directory. [Note: on some websites, your Document Root may have a different name than htdocs.]
  • You may have to enter the command lcd local-directory to change to the proper directory on your home computer.
  • Enter the command ascii or binary to switch to the appropriate transfer mode.
  • Enter the command put some-file to upload the file (where some-file is substituted with the real filename of the file you want to upload).
  • After uploading any of the .pl files, you must make them "executable" by a command like site chmod 755 geneal.pl.
  • When you have transferred all the files, enter the command quit.
• WS_FTP --
  • Run the WS_FTP program (from your Start Menu or by double-clicking the desktop icon).
  • Enter your website URL, administrative username, and password in the Session Properties dialog box.
  • Enter the source and destination directory names in both the Local System and Remote System window panes.
  • Select the ASCII or Binary buttons as appropriate for the file to transfer.
  • In the Local System file-list, click to highlight the file to transfer.
  • Click the ---> button in the center of the window.
  • After uploading any of the .pl files, you must make them "executable" by clicking to highlight it in the Remote System file-list, then right-click the file and choose chmod (UNIX) from the right-click menu.
  • Click to turn on the "Execute" check-boxes for "Owner", "Group", and "Other".
  • When you have transferred all the files, click the Exit button.
• Microsoft Front Page --
  • Run the Microsoft Front Page program (from your Start Menu or by double-clicking the desktop icon).
  • Enter your website URL in the Getting Started dialog box, and your administrative username, and password in the Name and Password Required dialog box.
  • In the left-hand file-tree window pane you select the directory you want to upload to.
  • To transfer a copy of the files, open an Explorer (i.e., a "My Computer") window, navigate to the source directory containing the files to transfer, and then drag-and-drop them to the right-hand pane in the Front Page window.
  • After uploading any of the .pl files, you must make them "executable". I know of no way to make Front Page do this, so you have to use FTP or WS_FTP as described above.

What should I use as my Images directory?

The easiest thing to do is just put your images in your Document Root. Then your Images directory is the same as your Documnet Root. If you don't like clutter in your Document Root directory, then you can create a subdirectory (using the mkdir command) in your Document Root, call it something like images and put all your image files in there.

Is there anything special I have to do if I want logging to work?

Yes. You need to do two things.

• First you need to create a subdirectory (using the mkdir command) named log inside your cgi-bin directory.
• Then you have to set the access permissions (using the chmod command) on the log directory so that the scripts can write log files in there. Because the web server runs with a different user ID than your login ID, you have to set the permissions to be "Write" for everyone ("Owner", "Group", and "Other").

What if I am the website administrator or I need more detailed instructions for the website administrator?

OK, much more detailed installation instructions, for various web servers and server operating systems, can be found here.

Preparing your breeding records database

What are these web database files?

There are two database files, and an index file for each, plus an index file for fast search capability, making a total of five files.

• The most important database file is the .dbw pedigree records file, which contains most of the information about each animal.
• Optionally you can include the .brw breeding records file, which defines all the breedings and offspring of each animal.
• The index files are used by the software to find information in the two main files more quickly. The index file for the .dbw database is the .ixw file.
• The index file for the .brw database is the .bxw file. This file is optional, you only need it if you also have a .brw file.
• The index file for fast searching the .dbw database is the .kxw file.
• You don't have to type in the index files; their contents can be generated automatically after you have created the two main database files: .dbw and optionally .brw.

What is the proper format for the .dbw pedigree database file?

The format of the database is one record per line, separated by end-of-lines, i.e., carriage-return and line-feed (CR/LF) on Windows NT, and simply line-feed (LF) on Linux/UNIX. Each line contains from 13 to 17 fields separated by the vertical-bar character in the following order:

1. record number
2. animal's name
3. whelp date
4. record number of sire
5. record number of dam
6. URL or filename of photo
7. conformance titles (e.g., "Am./Can. Ch.")
8. registration number (AKC, etc.)
9. description, e.g., coat color or breed/variety
10. sex, may be M, F, N, or S (male, female, neutered, or spayed)
11. awards (e.g., "C.D.X", "U.D.", etc.)
12. owner's email address
13. owner's website full URL
14. OFA Hips (optional)
15. OFA Heart (optional)
16. Thyroid (optional)
17. CERF (optional)

This is what an example line might look like:

• 1023|MyKennel's MyBeautiful Dog|w. 10 April 1976|1056|1833|http://www.alfirin.net/photos/mydog.jpg|Ch.|WD23454|sable|M|C.D.|owner@alfirin.net|http://www.alfirin.net/

This format is optimized for speed of processing by the ".pl" CGI scripts.

What is the proper format for the .brw breeding records database file?

The format of the database is one record per line, separated by end-of-lines, i.e., carriage-return and line-feed (CR/LF) on Windows NT, and simply line-feed (LF) on Linux/UNIX. This database is divided into two sections, the "animal records" and the "breedings records" section.
The "animal records" section lists all of the times an animal has been bred. Each line in this section contains 2 fields separated by the vertical-bar character in the following order:

1. record number of the animal
2. comma-separated list of the record numbers of each breeding

This is what an example line might look like:

• 1009|20011,20008,20010,20005,20009,20007,20004,20012,20006,20003

The "breeding records" section lists all of the offspring from each breeding. Each line in this section contains 4 fields separated by the vertical-bar character in the following order:

1. record number of the breeding
2. record number of sire
3. record number of dam
4. comma-separated list of the record numbers of each offspring

This is what an example line might look like:

• 20369|1745|3979|5106,2380,2382,4704,1385,2578

It is important that the record numbers you use for the breeding records are separate from the animal records, i.e., they are disjoint and don't overlap. One way to do this is to ensure that all your animal record numbers are less than some number, say 20000, and all your breeding record numbers are greater than that number. Some people choose to make the breeding record numbers a combination of the sire's and dam's record numbers. For example, a breeding record for a sire number 1029 and a dam number 3233 could be 1029x3233 (it is OK to have alphabetic characters in the index numbers).

What do I do with the two sections of the .brw file?

Just put the animal records section first, and then follow it with the breeding records section. You don't have to "mark" the sections in any way, or separate them.

I am unable to produce a .brw file ... does that mean I can't use the software?

The .brw file is optional. The web site software will work without it. But, you will only be able to display pedigrees, you will not be able to use the "breeding info" function.

If you use the "Make Index Files Utility" (described in the Uploading the Database section below), it will detect if you do not have a .brw file, and it will automatically create one for you.

I already have an existing database, how do I get my database in the right format?

This is a complicated subject....

• If you are using Breeders Assistant software to store your database, you are lucky: they can export your database directly to the web format. Breeders Assistant also automatically generates your .kxw file so that "fast search" will work. Beginning with version 4.51, it also properly handles the mapping of diacritically marked characters as used by many European alphabets.
• If you are using Breed Mate software to store your database, it can also export your database directly to the web format.
• If you already have breeding records in one of the other popular PC pedigree software programs, Breed Mate's "universal converter" might do the trick for you.
• If you are using K9-Ped software to store your database, it can export your database to the web format too.
• If you have Man's Best Friend Software (The Breeder's Standard), try the K9-Ped Data Transfer converter to get your database into Comma Separated Values format, then you can probably use either the K9-Ped "Make Index" program or the Online Converter Utility.
• If that doesn't work for you, and you can somehow get your database into Comma Separated Values (CSV) format, then you can probably use the Online Converter Utility.

I have Breed Mate. What is the export string I should use to export to .dbw/web format?

The default export string should be %2|[Name]|[DOB]|%3|%4|[Photo]|[Titles]|[Register] [Reg No.]|[Coat Colour] [Breed]|[Sex]|[User Field1]|[Owner Email]|[Owner URL] and it works great.

This Universal Converter sounds promising, where do I get it?

You can visit "our mates down under" at Wild Systems at www.breedmate.com. Their Universal Pedigree Converter supports 14 different pedigree database formats!

Breed Mate didn't work for me, but I can get my database into a Comma Separated Values (CSV) format. How do I use the Online Converter?

Convert your database from CSV format to the Database Web (DBW) format using the Online Converter Utility (click on the link to start the converter).

What do I do if I don't have the information for some fields, e.g., I don't know the whelp date?

Just leave that field empty. It may cause two of the vertical bars to be adjacent to each other. This is OK.

What do I do if I want to customize the scripts or the database; for example, add extra fields you don't already provide, e.g., inbreeding coefficient, etc.?

Either you can jam that information in one of the existing fields, or you can add more fields on the end, but this will require minor modifications to the script code.

View the slide show with a more detailed explanation of these options.

If after reading the slide show, you still don't know what to do, then contact me by email explaining exactly what type of customizations you want to try.

I will only be able to provide a limited amount of support. If you need extensive help, you should consult a web design professional.

Uploading the database

What do I have to do to the database(s) to get it/(them) ready for upload?

The very first time you create your database(s), it must be in the proper format.  See the Preparing your breeding records database section, above.  Once you have created your .dbw database file (and optionally, your .brw database file), and every time thereafter that you modify the database(s), you need to generate new index files.

How do I generate the index files?

• If you are using Breeders Assistant software, the index files are automatically generated for you when you use the "export" function.
• If you are using other software, you must run the mk_ixw "Make Index Files Utility" program.

Where do I get this "Make Index Files Utility"?

• Download the program from http://www.alfirin.net/pedigree-central/mk_ixw4.zip (910 KB).
• Open the ZIP file with WinZIP and click on the Install button.
• If you don't have WinZIP, just unZIP the files to a folder on your hard disk, and then run the Setup.exe program to start the Install.
• Follow the instructions of the Install program.
• When the Install is finished, you can run the program from Start > Programs > Pedigree Website Database > Make Index Files Utility (mk_ixw).
• The program will ask you whether or not your web server is Windows-based or not. It needs this information to properly build the index files because Windows uses both a carriage return and a line feed to denote end of line, whereas most other computers (UNIX and Macintosh) only use a line feed character.
• Click on the Browse button, select your database (your ".dbw" file), and click on the Open button.
• Click the Make Index Files Now button and it will generate the index files. It puts them in the same folder where your .dbw file is.

How do I determine whether my web server is Windows-based?

You should get this information from your ISP. Most web servers will not be Windows-based, they will be UNIX-based. Hint: if you are told that your web server is Internet Information Server (IIS), that's Windows NT; if you are told that your web server is Apache, that's UNIX.

OK, I have my index files generated. How do I upload the database and index files?

You can use FTP, WS_FTP, or Microsoft Front Page. See general instructions for obtaining and using these programs back in the Uploading the files to your website section. You should upload the files as follows:

• your-breed.dbw -- Usually put in your cgi-bin directory, upload in ASCII mode.
• your-breed.ixw -- Usually put in your cgi-bin directory, upload in ASCII mode.
• your-breed.brw -- Usually put in your cgi-bin directory, upload in ASCII mode.
• your-breed.bxw -- Usually put in your cgi-bin directory, upload in ASCII mode.
• your-breed.kxw -- Usually put in your cgi-bin directory, upload in ASCII mode.

You said "usually"... when would I not put those files in my cgi-bin directory?

The scripts expect to find the database files in their "current directory" when they run. On almost all web servers, the "current directory" of running scripts is the cgi-bin directory. In rare circumstances, the "current directory" may be your Document Root directory, or some other directory. You will discover this is the case if the scripts produce a Cannot open database error message when you run them from a web browser. The only way to find out the exact correct directory to put the database files in is through some experimentation. If you have this problem, contact me by email for assistance.

Troubleshooting

I have a Mac, and when I click on the Search Now button of "search.html", nothing happens.  What's wrong?

This is due to a bug in search.html introduced when the JavaScript form validation was added.  Download and install version 4.6.28 or later to fix this problem.

I have a PC with Internet Explorer version 5.5 or lower, and when I click on the Search Now button of "search.html", I get the message "'Undefined' is undefined".  What's wrong?

This is due to the same bug in search.html introduced when the JavaScript form validation was added.  Download and install version 4.6.28 or later to fix this problem.  You can also solve this problem by instructing everyone to upgrade to Internet Explorer version 6.0 or later.  This can be done by visiting http://windowsupdate.microsoft.com.

When I click on the "Search" button, it cannot find my ".dbw" file. Why?

It might be one of the following reasons:

• You put the database files in the wrong directory. Usually they must go in the same cgi-bin directory where the scripts are stored. If your web server is Windows NT based, you may have to put the database files in your root directory.
• Your web server is UNIX based and there is a type mismatch between the database filename and what you put in the config.pl file. This frequently happens when you name your database something like poodle.dbw with all lower case letters (a good idea) and you wrote it that way in config.pl as well. But your personal computer is Windows based, and Windows stores the file as Poodle.dbw (with a capital P at the front) and uploads it to your web server that way. UNIX based web servers are case-sensitive, so it thinks poodle.dbw and Poodle.dbw are two different files instead of the same file. The quickest way to fix this is to use the rename command of your FTP program, and change the filename on the web server to all-lower-case letters.
• Your database files may not have permission settings that allow them to be opened and read by the scripts. The scripts run as a user-id (typically "www", "web", or "httpd") other than your own login-id, so the files must have "read" permission turned on for "others". On UNIX web servers, use "chmod 644" to set the correct permission for data files. On Windows NT web servers, use IIS Manager to set the permission to "Read" for "Everybody".
• The directory/folder where your data files reside may not have permission settings that allow them to be opened and read by the scripts. The scripts run as a user-id (typically "www", "web", or "httpd") other than your own login-id, so the directory/folder must have "read" and "execute" permission turned on for "others". On UNIX web servers, use "chmod 755" to set the correct permission for directories. On Windows NT web servers, use IIS Manager to set the permission to "Read" and "List Contents" for "Everybody".

When I click on the "Search" button, I get a "Permission denied" or "HTTP Error 403" message. What now?

It might be one of the following reasons:

• Your website is probably not activated for CGI scripting. Contact your ISP and upgrade to CGI scripting service.
• Perhaps you spelled /cgi-bin wrong.
• The script files may not have permission settings that allow them to be executed. The scripts run as a user-id (typically "www", "web", or "httpd") other than your own login-id, so the script files must have "read" and "execute" permission turned on for "others". On UNIX web servers, use "chmod 755" to set the correct permission for scripts. On Windows NT web servers, use IIS Manager to set the permission to "Script" and "Execute" for "Everybody".
• The directory/folder where your script files reside may not have permission settings that allow them to be executed. The scripts run as a user-id (typically "www", "web", or "httpd") other than your own login-id, so the directory/folder must have "read" and "execute" permission turned on for "others". On UNIX web servers, use "chmod 755" to set the correct permission for directories. On Windows NT web servers, use IIS Manager to set the permission to "Script" and "Execute" for "Everybody".

When I click on the "Search" button, I get a "CGIwrap Error: Script is not executable" message. What now?

You forgot to make the "/cgi-bin/geneal.pl" CGI script executable. Go back and follow the instructions above in the Uploading the files to your website section to do that.

When I click on the "Search" button, I get an error message something like "CGI Error: The specified CGI application misbehaved by not returning a complete set of HTTP headers. The headers it did return are: Can't exec D:\some-directory-path-here\cgi-bin\geneal.pl line 1.". What now?

The fact that the error message indicates a path containing C:\, D:\, etc., is a hint that your web server is Windows-based (Windows NT, 2000, or XP). Windows web servers often have a problem where they don't provide the scripts with a proper "Current Working Directory" when they execute. The way to work-around this is to find and change every .pl script file that has a line in it that looks like require "some-script.pl"; and change it to require "D:\some-directory-path-here\cgi-bin\some-script.pl";. Obviously, you have to fill in the italicized bits with appropriate values for your web site. Also, IMPORTANT: due to the rules of the Perl language, any backslash characters you put inside quoted strings must be DOUBLED, like this: require "D:\\some-directory-path-here\\cgi-bin\\some-script.pl";

When I click on the "Search" button, I get a response that looks strangely like the Perl code for the "/cgi-bin/geneal.pl" CGI script.  What now?

Your website is probably not activated for CGI scripting. Contact your ISP and upgrade to CGI scripting service. If that's not the problem, perhaps you spelled /cgi-bin wrong, or your /cgi-bin directory does not have the correct permission settings. If the latter, you will need help from your ISP to fix it.

When I click on the "Search" button, I get a "Interpreter file not found" message. What now?

The path to your Perl interpreter on the web server is different than expected. Contact your ISP and find out the full pathname of your Perl interpreter, then insert it on the first line of "geneal.pl" where it currently says #!/usr/local/bin/perl. Be certain to leave the #! in front, with no spaces between the exclamation mark and the interpreter's pathname.

When I click on the "Search" button, I get a "500 Internal Server Error" message. What now?

This can be caused by a number of problems:

• The Perl interpreter is not installed on your web server. Install it, or get your web server administrator to do so.
• The Perl interpreter is installed at a path other than /usr/local/bin/perl. Get your web server administrator to create a symbolic link to /usr/local/bin/perl, or change the first line in every script to have the correct pathname.
• The scripts are in a directory that is not readable by the userid that the web server software is running as (usually "httpd" or "www", etc.). Use "chmod" to make the directory readable by "User", "Group", and "Other".
• The scripts are in a directory that is not allowed to run CGI scripts. Get your web server administrator to configure the directory properly. With Apache, it needs to be marked with "Options +ExecCGI" in the httpd.conf configuration file. With IIS, it needs to be set to "Executable + Scripts" permission.
• The scripts were accidentally FTP'ed up from a Windows PC to a UNIX/Linux server in Binary mode instead of Ascii mode, causing every line to have an unneeded carriage-return at the end (this drives Perl crazy). Upload the scripts again, this time using Ascii mode.
• The Perl interpreter thinks that there is a syntax error in a script. The easiest way to check this is log in to the server with telnet, cd to the cgi-bin directory, run the script from the shell prompt and see what it says. If you cannot telnet to your web server, you can install Perl on your home PC and try to run the script from a DOS prompt.

My ISP says they use Windows NT and only support Active Server Pages. What now?

I tried to make the pedigree program work in Active Server Pages, but it was way too slow. Tell your ISP to download Perl from www.activestate.com and install it on your web server. If they won't do it, find a different ISP who actually wants your business.

My ISP says they use Sun Web Server and only support Java. What now?

I tried to make the pedigree program work in Java, but it was way too slow. Tell your ISP to download Perl from www.sunfreeware.com and install it on your web server. If they won't do it, find a different ISP who actually wants your business.

My ISP's website administrator says he or she needs more detailed instructions.   Can you help?

Sure.  Much more detailed installation instructions, for various web servers and server operating systems, can be found here

The search page works, but the pedigrees come up funny and have -1's in them. What's wrong?

You must have uploaded the database and/or index files in Binary mode instead of ASCII mode. Upload the files again using the correct transfer mode.

I tried that and still no luck. Any other ideas?

If your web server is running Windows NT and Internet Information Server (IIS) or Windows 95/98 and Personal Web Server (PWS), then you need to make sure you answered "yes" to the "Is your web server Windows-based" question when you ran the "mk_ixw" program. Re-generate the index file(s) for your database(s) by running the "mk_ixw" program again, answering the question correctly, and upload it/(them) to the web server.

Slow search is working, but fast search doesn't return any results. What's wrong?

• Most common cause: You entered more than one word for fast search. Fast search can ONLY locate a single, full word. If you want to search for a partial word or multiple words, you MUST use slow search.
• Next most common cause: You need to generate a .kxw file. To do this, use the "Make Index Files Utility" program. After building new index files, you MUST upload all the files to the "cgi-bin" folder of your web site for the changes to take effect.
  TIP: A common mistake is to forget to rebuild the index files after making ANY change to the database. You MUST do this every time.

Slow search and fast search are working, but searching for a Sire or Dam in trial.pl ("[TRIAL PEDIGREE]") or entry.pl doesn't return any results. What's wrong?

• Most common cause: Your .dbw database file is using the wrong values for the Sex field, e.g., "Sire" and "Dam", or "Stallion" and "Mare". The Sex must only be one of the following:
  • "M" for Male
  • "F" for Female
  • "N" for Neutered
  • "S" for Spayed

Why doesn't the page hit counter at the bottom of "search.html" work?

You have to re-create the page hit counter. Either you must use Front Page to insert a "web-bot" Hit Counter, or you must obtain and insert a CGI script (you can find them on the Internet) to do page hit counting for you.

I have Front Page, but I can't find this "web-bot" Hit Counter you mentioned. Where is it?

You probably have Front Page 97. The web-bots are in Front Page 98 or Front Page 2000. Go buy an upgrade to Front Page 98 or 2000. If you have Front Page 98, look for the toolbar button that has an icon that looks like a robot. If you have Front Page 2000, look for the toolbar button that has an icon that looks like a machine gear.

I tried an #exec style server-side include to do page hit counting, but I get an error. What's wrong?

Your website may be configured with Microsoft Front Page Extensions, which disables server-side includes. You can test to see whether you have Front Page Extensions by entering the following URL in your browser: http://www.your-website.com/cgi-bin/geneal.pl?ident=Yes. This will usually show a message on the top of the page indicating the name and version of your web server software, and whether or not Front Page Extensions are active.

Why is this so complicated and why can so many things go wrong?

Developing web services is currently in it's "Wild West" phase. The software tools are not dominated by Microsoft, as desktop PC software development is, because they were a latecomer to the web server software scene. Not only do you have to deal with the vast differences between the way UNIX web servers act compared to Windows NT web servers, but web server software in general is highly configurable. Every ISP does things in a slightly different way, for their own reasons, and as a result, it is impossible to prepare "one size fits all" instructions. All is not lost; with patience, you should be able to get it to work the way you want. The amount of time it will take depends on how many of the "non-standard gotchas" you run into, and also upon your level of existing familiarity/expertise with web concepts. Experienced people have got it running as quickly as 15 minutes. Those less experienced have taken longer depending upon the number of concepts they had to learn. One week has been typical, on average.

Changes last made on: Wed 2 Apr 2008 8:43 PM PDT.