====================================

Readme for the OpenHPI Client/Daemon

====================================

This file documents the OpenHPI daemon and client libraries for the current

release.

The OpenHPI daemon runs as a background process and accepts connections from

remote clients to perform OpenHPI library function calls. The daemon wraps the

standard OpenHPI function library with a sockets-based API that is archicture

neutral for all types of clients.

The OpenHPI client library provides all the connection functionality needed by

the client application to connect to the OpenHPI daemon running on the local or

remote server.

Three ways of starting the OpenHPI daemon:

=========================================

There are three methods for starting the daemon at this point; manually 

calling the installed init.d script,  manually starting the daemon in 

the foreground, or automatically by installing the init script in one of

the system run levels.

1. Manually Calling Init Script:

-----------------------------------

You can START and STOP the daemon with the 'openhpid' init script.

This script can be found in $sysconfdir/init.d/openhpid (where the default

sysconfdir value expands to /usr/local/etc). 

You can change sysconfdir's value when you run configure using the

--sysconfdir=<mysysconfdir> argument. We recommend setting it to /etc.

Example To Start:

$sudo /usr/local/etc/init.d/openhpid start

Starting openhpid:			[  OK  ]

$

Example To Stop:

$sudo /usr/local/etc/init.d/openhpid stop

Stopping openhpid:			[  OK  ]

$

2. Installing Daemon into a Run Level:

--------------------------------------------

How you get the daemon to start automatically when the system boots

depends on your Linux distribution:

- Fedora/Mandriva: chkconfig --add openhpid; chkconfig openhpid on

- SuSE: yast

- Gentoo: rc-update -a openhpid default

- Debian: update-rc.d openhpid defaults

Manually Starting The Daemon:

---------------------------------------------

After performing 'make install' the init.d script will reside 

at $sysconfdir/init.d/openhpid and the executable itself at

$prefix/sbin/openhpid.

Usage of the openhpid executable:

openhpid [options] [-c <path to openhpi.conf>]

To start the daemon in the foreground use the '-n' option.

For more info 'openhpid -h'.

Example: 'openhpid -n -c /etc/openhpi/openhpi.conf'

More information on daemon parameters and evironment variables is given below.

The OpenHPI Daemon

==================

The daemon is compiled as a standalone application and can be run as either

a foreground or background application.

The daemon application and client libraries will be located in the openhpid

subdirectory.

When you run the daemon the standard method for locating the OpenHPI configuration

file is used. However, the daemon will accept a configuration file as a command

line option to override the default file.

An option in the configuration file determines the port number the daemon will

listen on for client connections. If a configuration file is not found the

the daemon will listen on port 4743 by default.

Currently, if you are not running as the root user, you must override the default

PID file location. Normally the PID file is created in the /var/run subdirectory.

This directory is not writable by normal users and only the root user can write

to this location. Thus the daemon will fail when run as a normal user if the PID

file location is not overridden. To override the PID file location you can use

the command line option.

     ./openhpid -f ./openhpid.pid

The OpenHPI Client Library

==========================

The easiect method to use to link to the client library is to first run the

OpenHPI installation script.

     make install

This will install the client library in the standard system locations. You can

now use the following link flags to link the client library to your application.

     -lopenhpi 

When you run your application the client library uses two environment variables

to locate the daemon service.

   OPENHPI_DAEMON_HOST - URL for the host running the daemon. This can be

                         "localhost" if the daemon is running on the local host

			 or an ip address.

   OPENHPI_DAEMON_PORT - The port number the host is listening on for clent

                         connections.

If the OPENHPI_DAEMON_HOST variable is not found the client library uses

localhost as the default. If the OPENHPI_DAEMON_PORT variable is not found then

the client library uses port 4743 as the default.

General Information

-------------------

The client and the daemon do not have to be on the same hardware architecture.

The daemon could be running on a P-series processor and the client running on an

x86-series processor. The client library and daemon use a marshaling technique

to resolve architecture and structure padding conflicts. The user does not need

to concern themselves with architectureal differences between the client and

daemon. The one exception to this rule is 64-bit architectures. The client and

daemon currently cannot resolve differences between 32-bit and 64-bit

architectures. DO NOT MIX THESE TYPES OF ARCHITECTURES!

It is important that data passed to the client library OpenHPI functions is

correct. Passing incorrect data could cause the client library or the daemon

to crash. The client library performs an extensive set of data validation

functions for each OpenHPI function, but it is still possible for bad data to be

missed by those functions. BE CAREFUL!.