BookAdder: Installation

But First!

Please be sure you have read the preceding BookAdder docfile About BookAdder for an overview before you plunge into these procedures. It only takes a moment or two, and leaves you better equipped to understand what you're doing and why. Please: RTFM!

The Very Easy Instructions

First Preparations

You will, of course, already have unzipped the ZIPfile in which BookAdder comes (or you wouldn't be reading this). Ideally, you will have made a separate subdirectory on your local computer for these files, so they don't get mixed up with anything else (perhaps named BookAdder. If that should not be the case, I strongly recommend you stop here and now and make such a separate subdirectory, then move all the BookAdder files into it--then come back to here.

Next, you need to make a directory on the computer hosting your site. I recommend you place it just off your site's root (main) directory. If those terms confuse you, your "root" directory is the directory containing the page your visitors would come to by just entering your site's basic URL into their browsers; say I entered http://seo-toys.com in my browser--the directory containing the page you see there is in my site's "root" directory. BookAdder should work properly no matter where placed on your site, but you really should give it a subdirectory of its own, and there's no special reason to go any farther down from your root than just under it.

If, however, you have multiple "sub-domains", then the logical place to put each one's BookAdder subdirectory is just below that sub-domain's chief directory (which may be a couple of levels below the true domain root); no problems, BookAdder just works wherever it is.

(I cannot tell you how to use your ftp software to work with files on your host--there is altogether too much variation in products. I can only tell you what you need to do. If you have trouble with this, perhaps--because using ftp software is a rather basic webmaster skill--you should obtain help from a professional in maintaining your site.

Select a name for your BookAdder directory. Use good SEO principles, and select a name that tells the search robots something about the directory contents: something like red-cats-book-shop is better than something like books. (Use hyphens, not underscores, to separate words in file and directory names.)

Create the directory. Then, if you are hosted on a Unix-based host system, set that new directory's "permissions" to either 777 or rwxrwxrwx (those are simply two different ways of specifying the same thing--some displays show permissions one way, some the other). If those terms seem "magical" to you, read the BookAdder docfile on Security-Related Concerns, which explains the basics of "permissions". The chances are that simply creating the new subdirectory will leave it permissioned at 755 (which is rwxr-xr-x); if so (and that varies from host to host, but 755 is common), you will need to explicitly change the permissions to 777. If you don't do this, there's a good chance that BookAdder will be unable to install.

If you have the misfortune to be hosted on a server running on one or another Windows operating system, "permissions" in this sense don't exist. The directory will be as "permissioned" as it gets just by being created, so don't try to "permission" it at all.

Now that you have a home on your host for the BookAdder files, simply upload them to it--all of them. (Do be sure to keep the originals on your local system as an emergency backup if anything ever corrupts the "live" ones on your host; that's wildly unlikely, but paranoics live longer.)

Verifying Usability

Presumably you know this, but to be sure I'll say it here once for all:

You "run" a PHP script by simply loading it into your browser like any web page.

PHP is a "scripting language". When your host receives a request for an ordinary web page, as indicated by an extension of .html or .htm or .shtml (or whatever else it's been set up to recognize as specifying HTML pages), it just fetches the file and delivers it over the internet to your browser. But when you request a page with a .php extension (or, again, whatever the server has been told specifies a PHP script), it fetches the file but first runs it through the PHP processor, which can do many things, including generate output lines; the server then takes the output from the PHP processor and sends that back to your browser. Typically, a .php page will contain a mix of PHP script instructions and normal HTML (internally marked so the PHP processor knows which lines are what), though a "PHP script" could be 100% plain, ordinary HTML--or have zero plain HTML. In that way, a PHP script can make a "dynamic" web page by constructing the page "on the fly" based on many changing things: what parameters your browser supplied in its call, the contents of certain local files (like, say, an inventory list), or even the time of day. That's how, for example, one BookAdder script can be the "front door" for six different national bookshops: it "knows" which shop it's supposed to be from a parameter supplied in the call, and serves the corresponding version of itself.

Your first step, once the BookAdder files have all been uploaded, is to run the script appropriately named tryme1st.php  The URL will depend on what you named your new directory and where you placed it, but if we assume that your website is www.friends-of-red-cats.com and that you named the new directory red-cats-book-shop and that you placed it right off your root directory, you'd run the script by entering this into your browser's URL bar:

http://www.friends-of-red-cats.com/red-cats-book-shop/tryme1st.php

In the best (and most common) of cases, its output will look something like this, depending in part on your browser's window size and font settings (and with, of course, your site's data showing instead):

In some cases, that display may also contain (just below the top headline) a message box that looks something like this:

That's pretty much self-explanatory, but there's a little more about it in the BookAdder docfile on Security-Related Concerns. The caution is just that: a caution--it does not mean that BookAdder will not work for you. But you should speak to your host about the matter.

If you got the OK screen, with or without the caution just described, and you have verified that all the data shown are correct, you may now proceed with installation. But, if either you got that screen but one or more of the data were wrong, or if you got an error message (with or without the warning just described), then you need to move to the docfile explaining those errors and what--if anything--you can do to cure the associated problem: click here for the BookAdder docfile Installation Problems.

You can verify the path on your server by what your ftp program shows, but be aware that Unix-based servers--and the majority are--have something called "symbolic links" that allows files and directories to have an "alias"; thus, the path you see in your ftp software may seem to differ from the one being reported on-screen and yet be the same. If they do not look identical, simply use your ftp software to try to reach the directory just as shown on screen. Typical differences might look like this:

· ftp software says: /usr/home/catfiend/public_html/catsite/red-cats-book-shop/

· screen reports: /usr/www/users/catfiend/public_html/catsite/red-cats-book-shop/

In that example, the screen is reporting the "correct" (real) directory path, while the ftp software is set to a "linked" path that ends up pointing into the identical directory. To verify, you would tell your ftp software to access what the screen reports and check that it is indeed the same place.

Since you're still reading, presumably you got no fatal-error messages and verified that the reported data are all correct. Excellent--now onwards.

Pre-Install Customization

You do this by using a plain text editor (not a word processor or HTML editor) to edit the BookAdder file cleverly named customize.php. In point of fact, that file is internally so heavily annotated that it is really self-explanatory, but let's go over it together anyway--measure twice, cut once, as the old carpenters say.

The very top of the file looks like this:

<?php

//  BOOKADDER: customize.php - v. 3.00 


//      Data you MUST customize:

//        1  2a  3  4


//      Datum you should customize if you are an Amazon affiliate:

//        5


//      Data you should customize if you are an Abebooks affiliate:

//        6a  6b

Below that are six entry areas separated off by rows of asterisks. The first looks like this:

/****** Step 1: Who are you? *****************************************************/

//  Change the datum below to the name of your site as you want it to
//  appear on all individual-edition display pages (where it will be
//  a link to you in large print atop the page).  Try to use as short
//  a title as you can, so it doesn't need to get folded onto 2 lines.
//  (This datum will also appear at the top of results pages from use
//  of the free-form Amazon search facility.)

//  I advise that you use one of these two forms:

//        The Something or Other Site
//   or
//        mywonderfulsite.com

//  depending on your tastes.  Mind your capitalizations!

//  Also: if the name is quite long--say over 30 or 40 characters--you can
//  force it onto two lines in places like larger-font headlines by putting
//  in, where you want the break, this exact character sequence:

//      <br/>

//  EXAMPLE: $myname='This Great Big Wonderful<br/>Super Web Site of Mine';

//  The break (if any) will NOT show when the name is given in small fonts.

//  ==============================================================================
//  CAUTION!  If your site name contains any single-quote ( ' ) marks,
//  you *must* put a backslash character ( \ ) just in front of each,
//  as in:

//       $myname='The "Boys\' Night Out" Site';

//  ==============================================================================


      $myname='The SEO Tools, Toys, and Packages Site';

In all cases, the datum (or data) are the values beginning with a  $  dollar sign and located on a line not started by  //  dual slashes. In this case, the datum is $myname, and you just change the sample entry--The SEO Tools, Toys, and Packages Site--to whatever you want, heeding the caution about marking any apostrophes and the advice about where and how to force long names to line-split when in larger type sizes.

The next data area down is just a hair more complicated, in that it has two sub-parts; it looks like this:

/****** Step 2: What is your search word/phrase? *********************************/

//  Choose the keyword or keywords you will use to search Amazon.

//  YOUR CHOICE IS QUITE IMPORTANT!

//  You want results that are reasonably relevant to your site,
//  but not too narrowly focussed.

//  For example, if your site is about a small town in rural
//  Washington State, you wouldn't want the town name in your
//  keyword phrase--something like 'Pacific Northwest' would
//  work better.  This is a matter of judgement.

//  The provided "bookcount.php" tool will tell you how many
//  books a given keyword phrase will likely find at Amazon.  
//  I suggest using a phrase that gives you a book count that
//  meets or exceeds Amazon's maximum of 4,000 titles, but
//  let common sense be your guide.

//  Be SURE to review the docfile "Tuning Your Search" before
//  finally settling on a phrase here.

/****Step 2a: your actual search phrase? *****/

//  This is the phrase Amazon will receive, and that thus determines
//  the results you will get.  Case does NOT matter, but I advise using
//  normal case, since you may end up displaying this phrase (see 2b).

//  ==============================================================================
//  CAUTION!  If your search phrase contains any single-quote ( ' ) marks,
//  you *must* put a backslash character ( \ ) just in front of each,
//  as in:

//       $keywords='O\'Reilly'

//  ==============================================================================

//  You can use multiple words if you want: just separate them with
//  plain blank spaces.  Example:  $keywords='flower gardens';

      $keywords='spokane';


/****Step 2b: the phrase to display? *********/

//  On several of the pages that the package displays to your visitors
//  appears the search phrase you are using here.  Sometimes--indeed,
//  often--the actual phrase you are sending to Amazon, as you have
//  entered it above, would make an awkward or clumsy display on a
//  web page (especially if you are using a so-called "complex" 
//  search); thus, you need to separately specify here the phrase that
//  will be displayed to your visitors to tell them what sorts of books
//  are in your bookshop.

//  As a simple illustrative example, if you want to get books about
//  "evolution" but not include books about "intelligent design",
//  you might use 

//    $keywords='evolution not "intelligent design"';

//  as your actual $keywords phrase; in such a case, you might want
//  your books description--as your visitors would see it--to be
//  something like "Scientific Evolution" or "Evolution Science".
//  One of those, or something like, would be what you enter here.

//  If you leave this datum as it is (empty), your actual Amazon
//  keyword/s search phrase as you entered it above at Step 2a will
//  be used for this purpose (so mind capitalization there!).

//  Take care with capitalization here--this is *exactly* what your
//  visitors will see on your site as your description.

      $keytext='Spokane, Washington';

Exactly because you are not yet ready to tune your search, I urgently suggest that for the moment you leave these two data just as they are set: they will make a nice, simple test case to see if everything is working, after which you can return to setting your own actual phrases.

The next data area is a short and simple one:

/****** Step 3: What is your front page named? ***********************************/

//  Chances are you will want to rename the "front page" of your new bookshop;
//  the sample provided is named  book-shop.php   but you might want to
//  rename it to, for example,  widget-books.php  .  This package needs to
//  know the name you will use, so it can properly set up internal links.

//  In the datum below, replace the name shown with the name you will use:

//  The spec MUST end in  .php  so don't try to fiddle that part!


      $myshop='book-shop.php';

You don't have to change this datum, now or ever. But it is wise to follow basic SEO principles and give your "front door" a meaningful name to help the searchbots in determining what your pages are focussed on. In the silly little example we have been using, you might call that page red-cats-book-shop.php. Don't "keyword stuff" the title, but do make it legitimately meaningful: use the same principles you would in naming it for human reading. Don't be afraid to give it the same name as the directory itself--in fact, that's probably a good choice.

The installer will use whatever name it finds here--book-shop.php or what you set instead--as the name of a simple little file it makes at install time, and which file just points on to the real bookshop page, which is always realshop.php).

The next data area down is even shorter and simpler:

/****** Step 4: Do you have a site icon file? ************************************/

//  If you have a Windows Icon graphic file that you use in  <link rel=
//  statements, place its FULL URL here--otherwise DO NOT change this.
//  A full URL might look like:  http://www.mywonderfulsite.com/favicon.ico


      $myicon='';

This is worth a comment. If you already have a favicon image file, just put its full URL in here. But if you don't (and leave the entry blank), you are missing a small but neat way to make your site a little more professional and memorable. A favicon is that little icon image that you see for many sites up in your browser's URL bar, just before the actual site URL. Your having a simple, distinctive favicon image helps your visitors remember and feel comfortable with your site--it's a small thing, but successes are built of many small things done right. Use your favorite search engine to seek out information on how to make and use a favicon file (you use it by calling it in the <head> area of your HTML pages. My only advice is the classic KISS (keep it simple, stupid). The images are very small, so keep yours clean and simple and easily grasped.

The last two data areas are for your Amazon and Abebooks associate ID codes. In the Amazon case, shown below, you can enter a code for any or all of the six national Amazon divisions; remember again that each division issues its own distinctive code--you cannot use one division's code at another. (Well, you probably can, but you wouldn't get paid for any sales!) Here is that entry area:

/****** Step 5: Are you an Amazon affiliate? *************************************/

//  IF you are an Amazon "Affiliate" and have an affiliate ID code,
//  enter it here--otherwise DO NOT change this datum!

//  As the instructions point out, if you ARE an associate, you and I 
//  will share sales credits on an average 50-50 basis, with particular 
//  sales being assigned at random (or as random as a php "rand()" gets).

//  Since each national division of Amazon is run separately, enter the
//  appropriate code for EACH national division at which you have a code.

//  BE CAREFUL!  Enter your Associate Code between the paired single-
//  quotation marks, like so:  $myUSid='owlcroft-20';

//  And, again, leave inapplicable divisions empty AS THEY ARE BELOW.


      $myUSid='';
      $myUKid='';
      $myCAid='';
      $myDEid='';
      $myFRid='';
      $myJPid='';

Be sure to get clear what you need to enter. You do not enter your "Access Key ID" or "Subscription ID"; you enter your associate ID, which typically looks something vaguely like redcats-20. The IDs, on the other hand, are long strings of nonsense letters and numbers jumbled together. You don't have to have any Amazon associations at all to actually start and run BookAdder, and you can insert individual divisional associate IDs as you get them: each will take effect immediately on your uploading of the revised customize.php file.

The last data area is the Abebooks one. There are now five Abebooks national divisions, and there are data-entry zones for each, but be advised: right now, only the main (US) Abebooks ID matters or is used. The others are there for future use. (It is my impression that the main operation lists virtually everything the others do anyway, plus you and your visitors can customize the results to select booksellers anywhere in the world, for delivery anywhere in the world, with prices in virtually any existing currency--so there's little or no loss.

The entry area looks like this:

/****** Step 6a: Are you an Abebooks affiliate? **********************************/

//  IF you are an Abebooks "Affiliate" and thus have an affiliate PID code,
//  enter it here--otherwise DO NOT change this datum.

//  If you ARE an Associate, you can get your PID Code value by going to the
//  Commission Junction site, logging in, and then getting the sample HTML
//  code for any Abebooks ad--any one will contain a pid=nnnnnnn statement.

//  As the instructions point out, if you ARE an associate, you and I 
//  will share sales credits on an average 50-50 basis, with particular 
//  sales being assigned at random (or as random as a php "rand()" gets).

//  (This uses only the U.S.-based Abebooks interface, though that in fact also
//  includes booksellers all round the world.)


      $myabe='';



/****** Step 6b: Are you an Abebooks-overseas affiliate? *************************/

//  IF you are an "Affiliate" of one or more of Abebooks' non-US divisions, you
//  can enter the corresponding PIDs here--otherwise DO NOT change these data.

//  As the instructions point out, if you ARE an associate, you and I 
//  will share sales credits on an average 50-50 basis, with particular 
//  sales being assigned at random (or as random as a php "rand()" gets).

//  (These use the appropriate Abebooks divisional interface.)

//  NOTE!!  These are not operational yet!  They are for future use only!


      $myUKabe='';
      $myDEabe='';
      $myFRabe='';
      $myESabe='';

I repeat: that second set is not functional yet. You can enter the IDs, if you have any, but only the main Abebooks interface will be used, and only the PID entered at Step 6a will be used there.

Now, as the last lines of the file say:

/****** Your customizing is done! ************************************************/
?>

(There is quite a bit more customizing that you can do, but we'll return to that after we have you up and running; this has just covered all the critical basic customizing necessary to run at all.)

Actual Installation

Note: if you are using, or ever used, any earlier version of this software, you should edit your robots.txt file to remove all exclusions specific to that package; you can spot them by the directory name in their path, that being whatever directory you were previously using for the software.

Before anything else, re-upload the newly modified copy of customize.php you just finished with. (Note that there is a backup copy of it, in case you ever screw anything up or otherwise want or need to re-start from scratch.) If you needed to re-permission the other files after upload (because of a problem detected running tryme1st), don't forget to re-permission this new upload, too.

Next, run the PHP script named finstall.php. Its output messages are color-coded: green for ok, grey for non-action notices, yellow for "note this", and red for problem warnings. Ideally, the display will look like this:

The exterminate.php script has been erased; upload it only when you need to use it!

DOC-about-bookadder.html: remaking with Permissions 0644: done OK.
DOC-bookadder-customizing.html: remaking with Permissions 0644: done OK.
DOC-bookadder-files-list.html: remaking with Permissions 0644: done OK.
DOC-bookadder-search-tune.html: remaking with Permissions 0644: done OK.
DOC-bookadder-security.html: remaking with Permissions 0644: done OK.
DOC-bookadder-upgrading.html: remaking with Permissions 0644: done OK.
DOC-installation-problems.html: remaking with Permissions 0644: done OK.
DOC-installing-bookadder.html: remaking with Permissions 0644: done OK.
LgNoImage.jpg: remaking with PHP as "owner": done OK.
MedNoImage.jpg: remaking with PHP as "owner": done OK.
NotAvailable: remaking with PHP as "owner": done OK.
NotBooks: remaking with PHP as "owner": done OK.
BookAdder.Files: remaking with PHP as "owner": done OK.
READ_ME.NOW: remaking with PHP as "owner": done OK.
abechange.php: remaking with PHP as "owner": done OK.
abedata.php: remaking with PHP as "owner": done OK.
abes.php: remaking with PHP as "owner": done OK.
adsense1.php: remaking with PHP as "owner": done OK.
allbooks.uk: remaking with PHP as "owner": done OK.
amazon-logo.gif: remaking with PHP as "owner": done OK.
amazon-message.php: remaking with PHP as "owner": done OK.
amazonmessage.htm: remaking with PHP as "owner": done OK.
attack.php: remaking with PHP as "owner": done OK.
avails.php: remaking with PHP as "owner": done OK.
book-search.php: remaking with PHP as "owner": done OK.
book-shop.php: remaking with PHP as "owner": done OK.
bookcount.php: remaking with PHP as "owner": done OK.
booksearch.htm: remaking with PHP as "owner": done OK.
bookshop.htm: remaking with PHP as "owner": done OK.
coopads.php: remaking with PHP as "owner": done OK.
cronf.php: remaking with PHP as "owner": done OK.
customize.php: remaking with PHP as "owner": done OK.
customizeBACKUP.php: remaking with PHP as "owner": done OK.
doall.php: remaking with PHP as "owner": done OK.
dofind.php: remaking with PHP as "owner": done OK.
exterminate.php: remaking with PHP as "owner": done OK.
findbooks.php: remaking with PHP as "owner": done OK.
finstall.php: remaking with PHP as "owner": done OK.
frb.php: remaking with PHP as "owner": done OK.
free.php: remaking with PHP as "owner": done OK.
freebie.php: remaking with PHP as "owner": done OK.
freepasses.php: remaking with PHP as "owner": done OK.
hold.htm: remaking with PHP as "owner": done OK.
holder.php: remaking with PHP as "owner": done OK.
know.php: remaking with PHP as "owner": done OK.
looknfeel.php: remaking with PHP as "owner": done OK.
looknfeelBACKUP.php: remaking with PHP as "owner": done OK.
makeindex.php: remaking with PHP as "owner": done OK.
makemaps.php: remaking with PHP as "owner": done OK.
makepw.php: remaking with PHP as "owner": done OK.
makestatic.php: remaking with PHP as "owner": done OK.
mapper.php: remaking with PHP as "owner": done OK.
nationals.php: remaking with PHP as "owner": done OK.
nonbooks.php: remaking with PHP as "owner": done OK.
phpinfo.php: remaking with PHP as "owner": done OK.
pings.php: remaking with PHP as "owner": done OK.
pull.php: remaking with PHP as "owner": done OK.
putback.php: remaking with PHP as "owner": done OK.
pwmake.php: remaking with PHP as "owner": done OK.
recommendedbooks.php: remaking with PHP as "owner": done OK.
rollyourown.php: remaking with PHP as "owner": done OK.
runcoopads.php: remaking with PHP as "owner": done OK.
search.php: remaking with PHP as "owner": done OK.
showstyle.php: remaking with PHP as "owner": done OK.
status.php: remaking with PHP as "owner": done OK.
timer.php: remaking with PHP as "owner": done OK.
tryme1st.php: remaking with PHP as "owner": done OK.
unavails.inc: remaking with PHP as "owner": done OK.
used-books.php: remaking with PHP as "owner": done OK.
usedbooks.htm: remaking with PHP as "owner": done OK.
washington-state-books.php: remaking with PHP as "owner": done OK.
watch.php: remaking with PHP as "owner": done OK.

Subdirectory /usr/www/users/catfiend/catsite/red-cats-book-shop/backups/: created OK.
Subdirectory /usr/www/users/catfiend/catsite/red-cats-book-shop/bookpages/: created OK.
Subdirectory /usr/www/users/catfiend/catsite/red-cats-book-shop/count/: created OK.
Subdirectory /usr/www/users/catfiend/catsite/red-cats-book-shop/logs/: created OK.
Subdirectory /usr/www/users/catfiend/catsite/red-cats-book-shop/trapfiles/: created OK.
Subdirectory /usr/www/users/catfiend/catsite/red-cats-book-shop/working/: created OK.

Copied file amazonmessage.htm to backup file amazonmessage.000
Copied file booksearch.htm to backup file booksearch.000
Copied file bookshop.htm to backup file bookshop.000
Copied file hold.htm to backup file hold.000
Copied file usedbooks.htm to backup file usedbooks.000
Copied file adsense1.php to backup file adsense1.000
Copied file customize.php to backup file customize.000
Copied file coopads.php to backup file coopads.000
Copied file freepasses.php to backup file freepasses.000
Copied file looknfeel.php to backup file looknfeel.000
Copied file rollyourown.php to backup file rollyourown.000

book-shop.php copied to red-cats-book-shop.php OK.

Tentative replacement robots.txt file (named robots.new) created.

Existing Sitemaps Index file updated as required.


If there are no red warnings or error messages above,
all needed subdirectories and files would now seem to exist.

You should make a reference note of the information below:

     Your PHP "Server Interface" is CGI

     PHP "Safe Mode" is set to Off.

You can re-run finstall.php at any time, as many times as you like. It will know what has already been done and will behave nicely. If you do, though, take note that some of the messages will change, and will be in grey or yellow instead of green, since the installer is notifying you of what is, not what it has done. For example, this would be typical after the file roll call (the display is slightly shrunken down here to fit better):

Now you're ready for a trial run.

(If you got through tryme1st.php without any problems showing, nothing should have gone wrong here; but if you did get a red warning message, e-mail me and we'll work it out for you.)

Doing a First Run

This is simple: load the file doall.php?test=y. With that attached test=y parameter, you'll be able to see its work as it progresses. The first thing you should see is the currency-exchange rates (as against the U.S. dollar) for the five non-U.S. Amazon divisions' national currencies, something that doall.php fetches (or freshens) every time it's called. That would be this:

Then it will begin the actual searching, going division by division. That, for Amazon U.S. (Amazon.com) begins something like this:

That header tells you the division it's doing (Amazon.com, the U.S. Amazon), what "keyword" phrase it's searching with (spokane), how many pages of results there are to get (12, though that may vary, depending on Amazon's stock), and that it's actually begun. (Were it picking up an interrupted search, it would say CONTINUING inseatd of BEGUN, and the number would be the number of pages left to get, not the total available).

The various right-arrow (») and dot (·) symbols tell you which script is actually sending the text: the » means doall.php is saying it, but any dots following mean, first dot, dofind.php (which is the "slave" that doall starts) is sending, and a second dot means, in turn, that findbooks.php, the secondary "slave" run by dofind, is the source. To clarify:

Most messages originate with findbooks, because it's the workhorse actually doing the job. Only when the job is completed (or interrupted in some way) do the intermediaries have anything to report to you.

You may, at this point be wondering about the complexity of the task, and of the sequence of master-slave processes involved. This pattern evolved out of numerous bitter experiences with the limitations of various host servers when running jobs that take some time to complete, or use up some chunk of memory, or both. All too often, such processes, of which these runs are examples, just mysteriously and more or less randomly "die" mid-operation. Exact reasons are hard to determine, even from the best of hosts; the fails are irregular and not repeatable. To try to minimize problems, the scheme you have just seen evolved. The thing starts with doall, which organizes the six separate divisional searches. For each such search in turn, it starts a copy of the dofind script, which is the active controller; it monitors output from dofind, which issues (and relays) progress reports, but if dofind dies before it has completed its task, doall simply re-starts it (that cycle can go for up to five attempts before it gives it all up as a bad job). Meanwhile, dofind starts the real worker script, findbooks.php, which reports back page by page as it progresses through the search. If findbooks dies, dofind restarts it, but only from where it had gotten to (hence the INDEX # parameter you'll see below), not from the beginning, so the work that had been done is not lost and does not have to be pointlessly re-done. And so it goes . . . .

Now here's a sample of how the reporting continues while findbook is getting data pages from Amazon. This trial task was deliberately set to produce a rather small amount of results, so it can finish up in a few seconds while you watch.

"Yesterday's count" is zero because there wasn't any run yesterday: this is the first ever. BookAdder has a safety feature such that if today's count is ever less than 80% of yesterday's, it assumes something went wrong and leaves yesterday's data in place; that way, you won't ever get a failed search largely or wholly wiping out your bookshop pages.

If that safety is not tripped, BookAdder proceeds to further process the downloaded data and make the 27 individual drop-in blocks for the bookshop's listing pages (remember that we are stil just doing the first of six divisions). The messages will look like this (where "@" signifies the non-alpabetical characters block):

Note that if an alpha block had no titles, the messages will so inform you. We see that here with this limited sample, but you ought never to see that in a real run, except perhaps for letters like "X". Note that after making the 27 blocks for Amazon U.S., BookAdder also produces the all-in-one text file allbooks.us.gz, which is in "gzipped" format--it's compressed, but almost all browsers can read it direct (unlike a standard ZIP file), because modern browsers "know" the gzip algorithm.

After making everything needed, the scripts report their success and conclusion of their operations, like so:

The seemingly duplicate success reports are in fact first from findbooks then separately from doall (dofind doesn't bother).

Next, below the horizontal ruler, the process will begin anew at the next Amazon division in the sequence, which will be Amazon U.K. It will all look just about like the U.S. divisional run, save with the name changed, as in this snippet from the start:

So it will go, through all six divisions. There is no special final signoff message after the last division (Japan); the horizontal rule appears, and that's all she wrote.

Checking Your First Run's Log

Obviously you are not going to sit at a screen watching data fetches for one to two hours daily. Normally, the nightly run will take place automatically and out of your sight (we'll get later on to how to set up such automated runs). But you can always see what's happening or what happened by looking at the BookAdder log file, which is a simple plain-text file. That file is named simply Shop.Log, and will be found in the logs subdirectory the installer put in the BookAdder directory you made at the outset. You can view it on line with your ftp software, or even your browser, or download it and look at it with any text editor. A typical run record would start with a line like this:

Following those will be a blank line, then a block of lines for the search of the first of Amazon's national divisions, the U.S. one. That block will look something like this (except that these lines are so long that they will probably break in your browser's display of this docfile, so I've put blank separator lines in between the real ones, though there are no such blank lines in the actual logfile) :

You should be able to see the procession clearly enough: doall starts its "slave" process dofind.php, with the "us" divisional parameter supplied; dofind then tells us that it will indeed start up a search in the us division, which it does by invoking its slave process, findbooks.php, which does the actual grunt work. Then findbooks tells us it is indeed starting, and from the beginning ("Index #1").

Ideally, findbooks simply trudges through its task, taking several minutes (depending on how many titles it's looking for), and finally completes satisfactorily, telling us so on the next line. Following its completion, it expires and its "master", dofind then also reports its success. It, in turn, expires, and finally doall acknowledges the divisional-task completions with a couple of message lines of its own, and the U.S. division task is completed. And so it should go through the whole set of six divisions.

Checking Your First Run's Results

Now the moment you've awaited. Just point your browser at your bookshop front-door file, the one you named back in customize.php--let's say it's red-cats-book-shop.php, so you're looking at http://www.friends-of-red-cats.com/red-cats-book-shop/red-cats-book-shop.php. The page you see should look something like this:

(That sample page above is functional: once you have executed your trial first run, it will bring up real data; you just can't re-set the division in this docfile sample. Be sure to re-load this docfile after your real run is completed.)

What you need to do now is poke around your temporary new bookshop (temporary because we haven't yet customized your search phrase to something relevant to your site.) Look at everything, and make sure it all looks right to you. All links should work, all pages should look correct. (Do remember, of course, that with this low number of titles, many alpha pages will have no listings--that's not a flaw as long as there are some real ones here and there.)

Further Checking Your Results

There is a handy little tool named status.php included in BookAdder. After poking about, you can also use this to get a clearer status report. Run it (it needs no parameters, just call it by name). The display below is not what you would see after your first trial run (for one thing, that run makes no sitemaps); the sample below is more representative of an actual, operative bookshop--though, in this example, one not SEO-optimized to get at least 4,000 "raw" titles from every division.

Note that even this non-optimized shop is adding about thirty thousand pages (29,932, to be exact) to its associated site. As it says elsewhere, page counts from 45,000 to 50,000 are possible with fully optimized search phrases.

If anything--in the Status Report or anywhere--seems wrong at this point, and especially if it seems very wrong, double-check your customizations in customize.php. If you can't find any errors, e-mail me; try to describe the problem in as much detail as you can, and don't forget to give me the URL of your BookAdder directory.

If--as will normally be the case--everything looks good, it's time to set you up with a real search phrase and get you going (you are not ready to open up yet).

Moving On

BookAdder Documentation Files Available

They are:

• About BookAdder - a useful overview of what BookAdder does, how, and why
• Installing BookAdder - this file
• Installation Problems - causes and cures for snags encountered when installing
• Tuning Your Search - how to easily optimize your search phrase
• Further Customizing BookAdder - ad displays, look-and-feel, and other aspects of customizing
• Security-Related Concerns - understanding the hows and whys of several related matters
• Upgrading - how to proceed if you have an earlier version installed
• BookAdder Files List - the purpose of every file in BookAdder: worth reading for tips'n'tricks

What to Read Next

You are ready to pick your real search phrase. Click on to proceed to the Tuning Your Search docfile.