Automated Library Management

Andrew D. Lewis andrew@mast.queensu.ca

24 November 1998

1 What Are we Doing?

I have written some programs which I use to manage my collection of books which I loan to my colleagues. The principle feature of my setup is that you can arrange to send, to anyone who has a book loaned out, email on a regular basis (say once a month). You can also send mail to selected people any time you like.

2 What You Should Have

You should have the following files and directories:

  1. The files 00readme.txt, 00install.txt, x.script where x ∈
     {bookrecall,books,loancheck,loanentry} and similarly four .man files.

2. There will also be some copyright files.

  3. The Makefile.

4. The directory doc containing the L^{A}TEX documentation.

5. The directory tmpl which contains templates for the messages which

     bookrecall sends.

3 The Setup of the Reference File

The first thing you are going to have to do is make a file which contains the information on your books. This file must be structured as outlined here. For each book you have, make an entry in the file which looks like:

    %%entry
    <AUTHOR>Jules Verne</AUTHOR>
    <TITLE>Twenty Thousand Leagues Under the Sea</TITLE>
    <LOAN></LOAN>

If the book is on loan to someone, put their email address in the <LOAN></LOAN> field. Make sure that the email address contains an @ (as all email addresses do) for reasons discussed later. The formatting of the author and title fields is flexible. First of all, their presence is optional (this is not true of the <LOAN></LOAN> field). If the fields <AUTHOR></AUTHOR> or <TITLE></TITLE> are not found, they are replaced with strings declaring them not found. The information need not be started on the line immediately following the %%entry delimiter.

When the file has been completed, put it in a suitable directory. Let us, for future reference, call this directory BOOKDIR.

4 The Mail Template Files

In the tmpl directory you will see three files: recall.tmpl, recallf.tmpl, and recallq.tmpl. These files are used to format the outgoing mail messages sent by the bookrecall script. In each file the string %AUTHOR appears where you want the book’s author to show up in the message, %TITLE appears where you want the book’s author to show up in the message, and %LOANEE appears where you want the email address of the recipient to show up in the message. For the automated recall, recall.tmpl is used, for the manual recall, recallq.tmpl is used, and for a final recall, recallf.tmpl is used.

5 Installing the Files

Edit the Makefile to set the location of the executables and the man pages, the location of Perl, the location of the L^{A}TEX documentation, and the location of the database file. The variable TMPDIR sets the location for some temporary files which are created by bookrecall. Then type make to set up the scripts, and make install to install them in the specified spots. To install the man pages, use make man.

If you do not have sed, see 00install.txt for instructions.

6 The bookrecall Script

What the program bookrecall does is:

1. Divides the data base file into blocks separated from one another by the

     string %%entry.

2. From each block the author, title, and loanee information are determined using the format of the input file.

3. The loanee information is searched for occurrences of the string @ (this is why the @ must appear in the email address).

4. If there is an email address in the loanee information, a temporary file with an email message is created. The message that is sent depends on which template file is used (see Section 4).

5. A list of people to whom mail was sent is saved in a file recall.data which is kept in the BOOKDIR directory. A copy of this file is also sent to the user.

6.1 The Automated Recall

In this section we describe how the automated recall process works. First you need to make an entry in your crontab file. To do this type

    crontab -e.

This will pop up a file to edit. You want to make an entry which will run bookrecall at a specified interval. For example the entry

    00 4 1 * * /home/penelope/andrew/bin/bookrecall

will run bookrecall at 4am on the first day of every month. Of course, the path for the binary must be yours. It seems as if the full path must be specified (i.e., $HOME/bin doesn’t work).

6.2 The Manual Recall

It is possible that you may want to send mail at some time other than that when bookrecall is run with your cron job. It is also possible that you may only want to send mail to certain people on the loan list. These tasks are accomplished by bookrecall using the -q option. It works in exactly the same way as the unoptioned bookrecall except that you will be prompted for whether you want to send mail to each entry extracted from the reference file. The message sent to each person is pretty much the same as that with bookrecall and it can be changed in the script.

6.3 The Final Recall

If you really want the book back NOW, use the option -f (this may be used along with -q). The outgoing message will be different (see Section 4).

7 Some Extras

For my own convenience I have written some scripts which you may also wish to use. These are included in the directory bin.

1. The script books is used as

books [-i]string and will give as output any entry or entries which contains string. Specifying the option -i will make the search case insensitive. The script books calls the Perl script dbtool which is included in the package.

2. The script loancheck will look for anyone who has a book on loan by looking for occurrences of <LOAN>char… </LOAN> where char is any uppercase or lower case letter, or a number. This is helpful if someone loans a book but has no email address. At the end of its output loancheck also prints out the contents of the file recall.data.

3. The script loanentry simply brings up an emacs window with your reference file so you can make changes to it.

In each of these files you will have to make some changes to variables before you use them.

8 Usage Notes

Here are some caveats.

1. If you set the environment variable GREPDIR, this will be taken to be the location of the database file. Otherwise you will have to edit the script to ensure that the proper location is specified.

2. The programs are not really flexible, so be careful with your formatting of the reference file. If you follow the directions above, you should be OK.

3. The temporary files that are created are supposed to be removed after their usefulness has expired. If there are some odd files left in TMPDIR, this may be an indication that the program has crashed.

Please send any comments and errors to: andrew@mast.queensu.ca.