Controlling PB
==============

$Id: Controlling_PB,v 1.1 2001/03/04 19:01:30 oz6bl Exp $

A running copy of PB can be controlled in a number of ways. The simplest is 
to send signals to PB. PB may be stopped by means of the program 'stopppb'.
More complex control is possible using the FIFO commands.

Signals
-------

PB recognises the following signals:

	SIGHUP	The signal forces a re-initialization of the download control. See
		the README file for more detail on the download control.

	SIGTERM	This signal forces PB to terminate. It causes all open files to be 
		closed and writes information about the pass to the log file.

FIFO commands
-------------

PB listens to the FIFO /etc/pbpb/pb-fifo and recognizes a few commands:

	MONITOR
		Ask PB to send monitoring information to the named FIFO. This
		is intended to be used by a separate program that e.g. displays
		the information in a human readable form on a screen. The format
		of the information is described later in this document.
	DFILL
		Ask PB to send a Directory Fill command to the satellite.
	INITDL
		Ask PB to re-initialize the download control.
	QUIT
		Ask PB to terminate

The syntax for the commands is XML as defined in the following DTD (Document
Type Definition):


<!ELEMENT PB-commands (MONITOR, DFILL*, QUIT*)>
	<!ELEMENT MONITOR (FIFO)>
		<!ELEMENT FIFO (#PCDATA)>
	<!ELEMENT DFILL EMPTY>
	<!ELEMENT INITDL EMPTY>
	<!ELEMENT QUIT EMPTY>

Examples of encoded commands are:


<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE	PB-commands SYSTEM 	"PBcommands.dtd">

<PB-commands>
<MONITOR><FIFO>/etc/pbpg/pb-fifo</FIFO></MONITOR>
<DFILL/>
<INITDL/>
<QUIT/>
</PB-commands>


PB Monitoring Output
--------------------

The monitoring output from PB is XML encoded according to the following DTD:


<!ELEMENT PB-data (INIT, (STATUS | DOWNLOAD | FILES | LOG)*, FINAL)>
	<!ELEMENT INIT (SATNAME, MYCALL)>
		<!ELEMENT SATNAME (#PCDATA)>
		<!ELEMENT MYCALL  (#PCDATA)>
	<!ELEMENT STATUS (DSTAT, ID, BYTES, FBYTES, DBYTES, TBYTES, CRC)>
		<!ELEMENT DSTAT  (#PCDATA)> <!-- Directory status -->
		<!ELEMENT ID     (#PCDATA)> <!-- File to download -->
		<!ELEMENT BYTES  (#PCDATA)> <!-- Total bytes      -->
		<!ELEMENT FBYTES (#PCDATA)> <!-- File bytes       -->
		<!ELEMENT DBYTES (#PCDATA)> <!-- Directory bytes  -->
		<!ELEMENT TBYTES (#PCDATA)> <!-- TLM bytes        -->
		<!ELEMENT CRC    (#PCDATA)> <!-- CRC error count  -->
	<!ELEMENT DOWNLOAD (LNO, LTXT)>
		<!ELEMENT LNO  (#PCDATA)>
		<!ELEMENT LTXT (#PCDATA)>
	<!ELEMENT FILES (#PCDATA)> 
	<!ELEMENT LOG (#PCDATA)>
	<!ELEMENT FINAL EMPTY>


Examples of encoded output is as follows:


<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE	PB-data SYSTEM "PBdata.dtd">

<PB-data>
<INIT> <SATNAME>AO-40</SATNAME> <MYCALL>OZ6BL</MYCALL> </INIT>
<FILES>Marked for download 1</FILES>
<LOG>PB open: OZ7SAT</LOG>
<DOWNLOAD> <LNO>6</LNO> <LTXT>197E3   9876</LTXT> </DOWNLOAD>
<STATUS>	<DSTAT>Up-to-date</DSTAT> <ID>2746</ID> <BYTES>765436</BYTES>
	<FBYTES>46566</FBYTES><DBYTES> 33445</DBYTES> <TBYTES>34</TBYTES> 
	<CRC>0</CRC> </STATUS>
<FINAL/>
</PB-data>


The program 'pbctrl' included in this release, is an example of a program 
that exploits these possibilities.

