Running the SARA server and tools

This sections describes how to run the SARA server (sarad) and associated tools:

sarad

the SARA server.

corpadm

a program to manage user accounts.

localize

a tool to convert the big-endian corpus data to little-endian format where

required. If the corpustexts are not stored in /corpus/1.0, localize

must be used to update the indexes.

solve

a very basic client for testing purposes.

testnet

not included in sara.tar; it's on the CD.

sample

not included in sara.tar; it's on the CD.

sarad

sarad is the SARA server (formerly known as server).

A parameter file can be specified with the -p option; if none is given the default parameter file defined during configuration is used.

The server can be started in an interactive test mode using the -d option:

   server% sarad -d

   Type end to leave test mode

   > log user password

   ...

   > end

   server%

If the server is started normally it will background itself after initialization:

   server% /corpus/bin/sarad -p /usr/local/etc/corpus.prm

   Started server

   server%

corpadm

corpadm provides an easy way to create, modify and delete user accounts for the server. corpadm uses the default corpus.prm file; as with the server this can be overridden with the -p option.

   server% corpadm -p /corpus/adm/corpus.adm

   corpadm>

Commands available:

help: Online help.
users: List all the usernames.
add: Add a new user.
list: List a users details.
change: Change a users details.
password: Change a users password.
delete: Delete a user.

If you do not supply enough arguments to a command corpadm will prompt you for the required arguments.

Command names can be abbreviated as long as the abbreviation is unambiguous; currently the first lette can be used to specify the command.

Online Help

You can get help inside corpadm by typing help command. If you want to know which commands are available just type help and press <RETURN> at the Command? prompt:

   corpadm> help

   Command? <RETURN>

   Commands are:


     list                 - List a user's details

     users                - List all usernames

     add                  - Create a new user

     delete               - Delete user

     change               - Interactively change a users details

     password             - Change a users password

     help                 - Provide help on commands

     quit                 - Quit the admin program


   corpadm> help list


   COMMAND:

     list                 - List a user's details


   ARGUMENTS:

     user                 - the user to be listed


   corpadm>

List all usernames

users will list all the usernames registered for the server.

corpadm> users

    guest      lou        scotty     

corpadm>

Adding a user

The add command creates a new user; just answer the questions. Only the username and password are required.

   corpadm> add fred

   Real name? Fred Bloggs

   Organization? Fred Plc.

   Contact Address? fred@fred.co.uk

   Expiration Date (dd/mm/yyyy)? <RETURN>

   Password? derf

   corpadm: Created user fred

Listing a users details

Use list to see a users account record.

   corpadm> list fred

   User                    : fred

   Real Name               : Fred Bloggs

   Contact                 : fred@fred.co.uk

   Organization            : Fred Plc.

   Last Successful Login   : (never)

   Last Unsuccessful Login : (never)

   Account expires         : (never)

   corpadm>

Changing a users details

The change command will display the current value for each field of the users record; either type in a new value or just <RETURN> to accept the current value.

   corpadm> change fred

   Real name [Fred Bloggs]?

   > <RETURN>

   Organization [Fred Plc.]?

   > <RETURN>

   Contact Address [fred@fred.co.uk]?

   >  fred.bloggs@fred.co.uk

   Expiration Date [never]?

   > <RETURN>

   corpadm: Changed user fred

change does not change a users password; use password for that.

Changing a users password

Use the password command to change a users password.

   corpadm> password

   User?  fred

   Password?  d3rf

   corpadm: Password changed

   corpadm>

Deleting a user

User records can be deleted with the delete command.

   corpadm> delete fred

   corpadm: Deleted user fred

   corpadm>

localize

You shouldn't need to drive localize manually; configure should set up the Makefile so that make install calls localize with the appropriate options.

However, should you ever need to run localize, localize -h describes the available options:

   server% localize -h

   Usage: localize {-[Aabdiprtkh]} directory


      -A         Equivalent to -a -p -b -d -i

      -a         Fix accelerator files (*.acc)

      -b         Fix bibliography file (pbib)

      -d         Fix dictionary file (corpus.dct)

      -i         Fix index files (idxNNN/NNN/NNN.H*)

      -p         Fix path index file (files.pdx)


      -r dir     Relocate the paths in files.pdx to dir

      -t n       Set the number of texts to n.

                 Overridden by value in files.pdx if -p is used


      -k         Keep the backup copies of files


      -h         show this help message


      directory  The directory where the files reside


   server%

directory should be /corpus/Index/etc for the -a, -b, -d, -p and -r options.

For -i it should be /corpus/Index/idxNNN; each idxNNN directory must be converted individually.

The dir argument to the -p option should be the new location of the corpus texts, i.e. if the texts are in /corpus/texts then localize should be called as

   server% localize -r /corpus/texts /corpus/Index/etc

   ...

   server%

solve

The program solve returns solutions to a CQL query, which must appear on the command line. For example:

   solve frog

will enumerate all solutions to the query frog in the format returned by GET (minus the OK, of course).

The solve program uses a connexion to localhost to contact the server. It can therefore only be run on a machine that is running the server.

testnet

testnet is used to test the server. It accepts ASCII packages as documented in the BNC Manual which the user types at the prompt. The replies are echoed.

sample is a simple filter that may be used to reduce the number of solutions returned by solve. sample num reads lines from standard input and sends every numth line to standard output. For example:

   solve frog | sample 3

displays every third hit from the query frog.