home *** CD-ROM | disk | FTP | other *** search
/ back2roots/padua / padua.7z / padua / uucp / uupoll068.lha / misc / uupoll067.lha / uupoll.man < prev    next >
Encoding:
Text File  |  1992-07-16  |  33.1 KB  |  688 lines

  1.               __
  2.      /  //  //__)_  / /
  3.     (__/(__//   (_)(_(_
  4.  
  5.     the UUCP polling server                        R0.67 92/07/16
  6.  
  7.     (c)Copyright 1991,92 Ralf S. Engelschall, All Rights Reserved.
  8.     (c)Copyright 1991,92 Cyvaned Systems,     All Rights Reserved.
  9.  
  10.  
  11.                                   DISTRIBUTION
  12.  
  13.       This  material  is  neither  freeware nor shareware nor public domain.
  14.     It's  copyrighted because it was developed for own usage only but may be
  15.     freely destributed to help the Amiga community as long as no changes are
  16.     made  in  the  whole material and no charge is made for the distribution
  17.     except for magnetic media, mailing materials and postage.
  18.  
  19.       Using  this  program  implies  that  you  have  accepted  all  licence
  20.     statements and/or conditions specified within this document.
  21.  
  22.  
  23.                                    DISCLAIMER
  24.  
  25.       THE  AUTHOR  MAKES  NO  WARRANTIES,  EITHER EXPRESSED OR IMPLIED, WITH
  26.     RESPECT  TO  THE  MATERIAL  DESCRIBED  HEREIN, ITS QUALITY, PERFORMANCE,
  27.     MERCHANTABILITY,  OR  FITNESS FOR ANY PARTICULAR PURPOSE.  THIS MATERIAL
  28.     IS  PROVIDED  "AS  IS"  AND  THE  ENTIRE  RISK  AS  TO  ITS  QUALITY AND
  29.     PERFORMANCE IS WITH THE USER.  IN NO EVENT WILL THE AUTHOR BE LIABLE FOR
  30.     ANY  GENERAL  OR SPECIAL DAMAGES, INCLUDING DIRECT, INDIRECT, INCIDENTAL
  31.     OR  CONSEQUENTIAL  DAMAGES  RESULTING  FROM  THE  USE  OF  THIS  PROGRAM
  32.     (INCLUDING  BUT  NOT  LIMITED  TO  LOSS  OF  DATA OR DATA BEING RENDERED
  33.     INACCURATE  OR  LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
  34.     THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS).
  35.  
  36.  
  37.                                 RIGHTS RESERVED
  38.  
  39.       The  author  reserves  the right to make changes in the whole material
  40.     identified  in  this  puplication without notice and to distribute other
  41.     revisions under different licence statements and/or conditions.
  42.  
  43.  
  44.                                       NOTE
  45.  
  46.       Please  excuse my uneven english, because it's not my nativeĆ”language.
  47.     But  writing  this  documentation in german would decrease the number of
  48.     people  who  can  understand  the  function  of UUPOLL and I hate german
  49.     descriptions   of   international   spreaded  material  because  of  the
  50.     non-technical character of this.  Thanks in advance!
  51.  
  52.  
  53.                                      ABOUT
  54.  
  55.                                  SHORT OVERVIEW
  56.  
  57.     - controls the execution of a UUCICO child as the parent part
  58.     - checks for correct hostname and polling-time violation
  59.     - controls abortion of UUCICO due to a precalculated restriction time
  60.     - operates dependendly on status of last session
  61.     - operates dependendly on (specific) pending work
  62.     - controls dialup retries due to busy line or other UUCICO failures
  63.     - controls abortions due to user interupts
  64.     - can be disabled through a job control feature for crontab interventions
  65.     - can abort a startup due to or break an already running UUCICO process
  66.     - can give information about polling times and host status
  67.     - can setup your modem before start of a polling session
  68.     - can spawn UUCICO with additional options
  69.     - can spawn own user command after a (successful) session
  70.     - full UUCP logfile support similar to UUCICO
  71.     - can run under full runtime debugging with variable debug level
  72.  
  73.  
  74.                               DETAILED DESCRIPTION
  75.  
  76.       UUPOLL  is a polling server written for the UUCICO from the Amiga UUCP
  77.     package  (V1.15  or  later).  If you don't know anything about UUCP this
  78.     utility  won't  be  for you and you should stop reading here and discard
  79.     it.   If  you  have already installed and configured an UUCP package (at
  80.     least  the  transport  layer  and the main configuration from Amiga UUCP
  81.     V1.15D  or  later  is  needed)  on your system you should be able to use
  82.     UUPOLL  directly  without  setups.  If not, stop here and configure your
  83.     UUCP system first, really!
  84.  
  85.       You  will  probably  ask, why we need a polling server?  UUCP's UUCICO
  86.     command  handles  all  we  need  when polling a host, i.e.  all transfer
  87.     operations  in  detail.  So if you are polling your NewsFeed once a week
  88.     (which  is actually ok for a leafsite only!), calling UUCICO manually is
  89.     simple  and  works.   But  if you have many polling operations a day the
  90.     handling of UUCICO will actually require nerves of steel because it is a
  91.     simple  transfer  command  for UUCP connections only and doesn't provide
  92.     great comfort.
  93.  
  94.       Another boring thing to us was that we often need many polling retries
  95.     before  successfully  connecting  to  heavily loaded hosts with few idle
  96.     telco  lines.   At  this  situation we had to reenter the UUCICO command
  97.     manually for each retry operation while waiting in front of our machines
  98.     observing  the  polling  processes.  At first we had used a AmigaDOS(tm)
  99.     batch  script  distributed  with  AmigaUUCP  1.13D to automate the retry
  100.     procedure.   This  worked fine but not very elegant, because it used bad
  101.     things  like  a  dummy transfer file to check if UUCICO's last retry was
  102.     actually successful.
  103.  
  104.       Another  big  problem  (also not handled by UUCICO or the batch script
  105.     mentioned) is that UUCICO doesn't stop when the polling time is over due
  106.     to  a  given  time  restriction,  i.e.  the polling time is reserved but
  107.     limited  by  the  remote  system.  One of our remote systems for example
  108.     reserves  us  a  polling time of one half hour from four o'clock to half
  109.     past  four  every  morning to do all daily transfers.  No other host had
  110.     the  right  to  poll at this time interval.  This has the advantage that
  111.     there  aren't  any  retries  when  connecting  because the telco line is
  112.     explicitly  reserved  for  us.  The "disadvantage" is, that at half past
  113.     four another reserved polling time (of another host) starts, which means
  114.     that  we  have  actually  only the right to use the phoneline up to half
  115.     past four and no longer.
  116.  
  117.       At  half  past  four the phoneline have to be given free, otherwise we
  118.     will  become  a  great deal of flames from the sysop of the host polling
  119.     after us because we had used his reserved time interval.  Usually we had
  120.     a  connection  time  between 15 and 25 minutes on this polling sequence.
  121.     But  sometimes  there is so many traffic inside our requested newsgroups
  122.     that we still transferring data at half past four.  At this situation we
  123.     had to interrupt UUCICO because our polling time is over.  To solve this
  124.     problem  we  had  stopped  UUCICO  via  'break'  command  started by our
  125.     'crontab'  at  half  past  four.   This worked also fine but only little
  126.     elegant.
  127.  
  128.       The  next  big  problem  was  the fact, that after breaking UUCICO the
  129.     remote  host will hold not already transferred data until we poll again.
  130.     That's ok so no data will be lost.  But the really problem is that a lot
  131.     of data is waiting for us if we break the next polling session again and
  132.     then the next one also and the next one...  To solve this we had started
  133.     UUCICO at a second time (some hours later) where all host can poll which
  134.     don't  have  a  reserved polling-time.  So we had the ability to receive
  135.     all  remaining  data from this remote host at this session but we had to
  136.     do  this  manually  because  if  the first connection wasn't breaked the
  137.     second  one  would be redundant and cost phone units only.  The only way
  138.     to  solve  this correct and elegant is to know, whether the last polling
  139.     session was successful.
  140.  
  141.       You  see,  these  are  all  problems  which can be solved by writing a
  142.     intelligent   server   program  for  UUCICO  which  handles  _all_  this
  143.     situations  _automatically  without us_.  So UUPOLL mushroomed out of my
  144.     brian...
  145.  
  146.  
  147.                                   REQUIREMENTS
  148.  
  149.       As  mentioned  above you have to install a UUCP package like AmigaUUCP
  150.     from Matt Dillon (V1.15 or later) or compatible.  For detail have a look
  151.     at  the  manual  pages of _your_ UUCP software.  UUPOLL relies on UUCICO
  152.     and UUXQT of V1.15D or later only, but you should have a correct package
  153.     at all.
  154.  
  155.  
  156.                                   INSTALLATION
  157.  
  158.       If  you  have a already configured UUCP system, installing UUPOLL will
  159.     be  quite  simple:  Just copy UUPOLL to any place where you can find it.
  160.     Usually  UUPOLL  is staying at UUBIN:  where all other UUCP command are.
  161.     Of  course  you can give UUPOLL another name by renaming it.  It acts in
  162.     all situations with its AmigaDOS(tm) name.
  163.  
  164.       If its 'permanent' flag isnt' already set, please set it with 'protect
  165.     UUPOLL +p' because UUPOLL can be made resident.
  166.  
  167.       But  be  sure  that the following things are already configured before
  168.     you try to run UUPOLL successful.  Otherwise do it now!
  169.  
  170.       You  need  a  correct  UULIB:l.sys  file,  where  UUPOLL  can  extract
  171.     informations  about  the  host  you  want  to  poll (i.e.  if it exists,
  172.     baudrate,  allowed  polling  times).   This  should  already  exist  and
  173.     configured  correctly  because this is also used by SENDMAIL and UUCICO.
  174.     For  example,  have  a  look  at  a  part of UULIB:l.sys of site CyvaNT2
  175.     (angle.muc.sub.org):
  176.  
  177.       :
  178.       | # CyvaNT1 (cyvaned.sub.org)
  179.      !| cyvaned Any SER: 9600 ATS7=060DP97990 ogin: Uangle sword: XXXXXX
  180.       |
  181.       | # Alcolix (brumuc.muc.sub.org)
  182.      !| brumuc 04:00-04:30,08:00-10:00,12:15-12:45,13:15-15:00,
  183.     ... 16:15-18:30,19:00-20:30 SER: 9600 ATDP0893544971 in: Uangle rd: XX
  184.      !| brumuc 04:15-04:50 SER: 9600 ATDP0893544023 in: Uangle rd: XX
  185.       :
  186.  
  187.       As  you can see, `angle' has direct connections to hosts `cyvaned' and
  188.     `brumuc'.   At  `cyvaned'  there is one phoneline only, `brumuc' has two
  189.     phonelines.   Notice  that  UUPOLL supports such multiline entries, too.
  190.     Both  have  many  reserved times, so `angle' have to know all these time
  191.     intervals  where it is allowed to poll each host (these times are given,
  192.     not  the reserved ones!).  UUPOLL checks for these time intervals, so be
  193.     careful:   Take  them  up to date!  Notice, a bad time-field (the second
  194.     field) will produce a bad `host status' ("-i").
  195.  
  196.       If  you want to use the `automatic hostname' feature (which is useful,
  197.     if  you  poll only one host or one host the most of the time), i.e.  not
  198.     specifying  one  of  the  "-s" or "-S" option, make sure that UUPOLL can
  199.     open  a  file  called  UULIB:config  where  it  can  find  a field named
  200.     "DefaultHost".  For example, `angle's config-file looks like this:
  201.  
  202.       :
  203.       | NodeName       angle
  204.       | UserName       rse
  205.       | RealName       Ralf S. Engelschall
  206.       | Organization   Cyvaned Systems
  207.       | DomainName     .muc.sub.org
  208.      !| DefaultNode    brumuc.muc.sub.org
  209.       | TimeZone       CET
  210.       | LockDir        uuspool:
  211.       | MungeCase      N
  212.       | Debug          0
  213.       | Filter         ed -sticky
  214.       | RFilter        ed -sticky
  215.       | MailEditor     ed -sticky
  216.       | NewsEditor     ed -sticky
  217.       :
  218.  
  219.       UUPOLL  strips off domains automatically when extracting the hostname,
  220.     setting  this  field  to "brumuc", "brumuc.uucp" or "brumuc.muc.sub.org"
  221.     results always in a default hostname of "brumuc".
  222.  
  223.       If you want to use the modem setup function ("-m") make sure, that you
  224.     have a correct setup file called UULIB:modemsetup, which will be used by
  225.     UUPOLL  only.   This  is  the  only  introduction  of  UUPOLL, all other
  226.     configuration  files  should  already exist.  The layout of this file is
  227.     similar   to  NEWSCTL:sys  of  CNEWS,  which  specifies  the  newsgroups
  228.     interchanged  with each host.  Instead of explaining this, please have a
  229.     exact look at 'angle' ones.
  230.  
  231.       :
  232.      !| cyvaned:\
  233.       | ATZ,
  234.       | AT&W
  235.       |
  236.      !| brumuc:\
  237.       | ATZ,ATE1,ATH0,ATK1,ATL3,ATM2,ATQ0,ATV1,ATX4,\
  238.       | ATS0=000,ATS2=043,ATS3=013,ATS4=010,ATS5=008,\
  239.       | ATS6=002,ATS7=060,ATS8=002,ATS9=010,\
  240.       | ATS10=015,ATS12=050,ATS18=000,ATS25=000,ATS26=000,\
  241.       | AT&B0,AT&C1,AT&D2,AT&H1,AT&L0,AT&M0,AT&R2,\
  242.       | AT*A0,AT*D0,AT*E1,AT*F3,AT*P0,AT*Q0,AT*S1,AT*E1,AT*U0,\
  243.       | AT&W
  244.  
  245.       ATTENTION!   Don't  forget  the  "AT&W"  command at the end of your AT
  246.     command  sequence.   If  you  forget  this,  no setup effect will happen
  247.     because  when  UUPOLL  closes the serial.device after its modemsetup the
  248.     serial.device  will  drop the DTR (Data Terminal Ready) signal which has
  249.     the  result  that your modem will reset itself to its last configuration
  250.     which  had  exist  before the last AT&W command.  Use the third field of
  251.     UULIB:l.sys for setups which should not remain after the polling session
  252.     and use UUPOLL's UULIB:modemsetup for permanent setups only.
  253.  
  254.       BE CAREFUL!  Use the ModemSetup with care.  No, it has no serious bugs
  255.     in  code,  but has a lot of problems with the other commands of the UUCP
  256.     package, i.e.  UUCICO and GETTY.  The first problem occurs if you try to
  257.     poll   with   modemsetup  while  GETTY  is  running.   GETTY  locks  the
  258.     serial.device  explicitly,  so  UUPOLL  wouldn't  be  able  to  open the
  259.     serial.device.   The  second  problem comes up, if you try to run UUPOLL
  260.     with  the  LOCKSERIAL command.  This works fine for UUPOLL, i.e.  it now
  261.     could setup your modem, but UUCICO will hang forever because it tries to
  262.     lock the serial.device too and comes never back...  The only solution is
  263.     either  to kill GETTY when using the modemsetup function of UUPOLL or to
  264.     leave this feature unused.
  265.  
  266.       The  only  thing which UUPOLL uses and which you need not configure is
  267.     the  UUCP  logfile,  called  UUSPOOL:logfile.   Here, UUPOLL appends (as
  268.     UUCICO,  UUXQT,  SENDMAIL, etc.  do) his logbook-messages.  Notice, that
  269.     UUPOLL defaults to do no console output.  The only way to check what was
  270.     done  or went wrong is to look at this file (unless the runtime debug is
  271.     enabled).
  272.  
  273.  
  274.                                      USAGE
  275.  
  276.                                  SHORT OVERVIEW
  277.  
  278.     uupoll [-s [System]] [-S [System]] [-r Num] [-d Sec] [-t Min]
  279.            [-u Arg] [-m] [-e [Cmnd]] [-E [Cmnd]] [-n [User]]
  280.            [-a] [-p [Num]] [-c [Mode] [-j [Status]] [-i [Mode]] [-x Num] [-v] [-?]
  281.  
  282.     s  poll the specified system             u  additional uucico arguments
  283.     S  as 's' but ignore time restriction    m  setup modem before startup
  284.     r  number of retries before giving up    e  execute after polling session
  285.     d  seconds of retry delay time           E  as 'e' but execute always
  286.     t  minutes of restriction time           n  notify user if session fails
  287.  
  288.     a  always poll - ignore success status   i  current host status information
  289.     p  poll only if pending work             x  number of debuglevel
  290.     c  check for already spawned uucico      v  version info
  291.     j  switch/set job control status         ?  usage info
  292.  
  293.  
  294.                               DETAILED DESCRIPTION
  295.  
  296.     s  poll the specified system
  297.  
  298.           This  specifies the system which UUPOLL should poll.  Use the UUCP
  299.         name,  not  the  logic  one,  i.e.   at  `angle' I have to set it to
  300.         `cyvaned'  instead  of  `CyvaNT1' and `brumuc' instead of `Alcolix'.
  301.         If this option isn't used, UUPOLL extracts the hostname of the field
  302.         "DefaultHost" in UULIB:config.
  303.  
  304.     S  as 's' but ignore time restriction
  305.  
  306.           This  specifies also the system which UUPOLL should poll, but with
  307.         the  addition that this "profanes" the holy situation of restriction
  308.         time violation.  This is similar to UUCICO's -S option.
  309.  
  310.           The advantage of this option would be that you can use a polling trick
  311.         introduced by T.Lotterer (joedust@cyvaned.cyvaned.sub.org).  Think about
  312.         his  situation:   He wanted to poll one of his NewsFeeds and waits until
  313.         no  reserved  time  is  active because he didn't want to steal someone's
  314.         reserved  time.   Now  he starts to dialup his NewsFeed but the line was
  315.         busy, busy, busy...
  316.  
  317.           The  reason  why  this  happens  was  clear:   All other hosts act
  318.         similar.   The  only  solution  to  avoid this situation would be to
  319.         start  polling  a  few  minutes  before  all  other  would  do, i.e.
  320.         starting  _before_  the  reserved time would be over.  Oh, you think
  321.         thats  not  ok,  because  now we use someones reserved time?  That's
  322.         right, but no one would disagree because if someone is still polling
  323.         at  his  reserved  time,  he  could not be interrupted and if he has
  324.         already finished he has no reason why he should disagree with us.
  325.  
  326.           So if T.Lotterer wanted to poll his NewsFeed he waits until 30% or
  327.         more  of the currently active reserved time is over and then started
  328.         to dialup his NewsFeed.
  329.  
  330.           This  feature is also useful for debugging without having to alter
  331.         the l.sys file.
  332.  
  333.     r  number of retries before giving up
  334.  
  335.           This  indicates  the  total  number  of re(!)tries.  Remember that
  336.         retries  means  that  the first retry is trial number 2!  A retry of
  337.         zero (the default) forces UUPOLL to try only once and then give up.
  338.  
  339.     d  seconds of retry delay time
  340.  
  341.           This  indicates the number of seconds which UUPOLL will wait until
  342.         it  starts  a new dial retry.  Default is no delay time (0 seconds).
  343.         This  was  originally introduced for special situations to avoid too
  344.         many  dials which result in a lot of unused telephone units due to a
  345.         telephone number change without notice by one of our NewsFeeds.
  346.  
  347.           It also keeps the line a bit idle between retries, allowing remote
  348.         sites to log into your local system.
  349.  
  350.     t  minutes of restriction time
  351.  
  352.           If  specified with a number not equal zero this sets the number of
  353.         minutes  after  which  UUPOLL  should  terminate UUCICO.  This timer
  354.         starts  immediately  after you have started UUPOLL.  I call this the
  355.         'restriction time' for the polling session.  If this option is left,
  356.         UUPOLL  calculated the minutes out of the given time intervals found
  357.         in UULIB:l.sys.
  358.  
  359.     u  additional UUCICO arguments
  360.  
  361.           This  specifies  the  additional(!) arguments for the UUCICO call.
  362.         UUPOLL  starts  UUCICO  always  with  "UUCICO -S{hostname}" and will
  363.         optionally add this string to the end of that `calling command'.  If
  364.         you  wish  no  addidtionl  args  you have to specify `-u' only.  The
  365.         default   is   "-7"   which  indicates  that  UUCICO  should  use  a
  366.         7-Wire-Handshake.
  367.  
  368.           But  notice,  you  have to specify the option argument string in a
  369.         special  form  if  you use a seperation blank between UUPOLLs option
  370.         and  the  option  argument.   You have to write `-u " -X -Y -Z ..."'
  371.         instead of `-u "-X -Y -Z ..."' (notice the blank character after the
  372.         first  quotation  mark!).   This  is no bug in UUPOLL, its a special
  373.         case in option parsing.
  374.  
  375.     m  setup modem before startup
  376.  
  377.           If  specified  this indicates UUPOLL to setup your modem according
  378.         to the commands found in UULIB:modemsetup before it starts the first
  379.         UUCICO process.  See INSTALLATION above for detail.
  380.  
  381.     e  execute after polling session
  382.  
  383.           This  specifies  the user command which will be executed by UUPOLL
  384.         after a polling session.  The default is the UUXQT command.  It will
  385.         be executed after..
  386.             .. a successful UUCICO session
  387.             .. UUPOLL was aborted due to a restriction timeout
  388.             .. UUPOLL was aborted by the user
  389.                or by a UUCICO break/software error
  390.         To disable the execution of a user command specify `-e' only.
  391.  
  392.           Please  note  that  UUPOLL prevents UUCICO from executing UUXQT in
  393.         general.
  394.  
  395.     E  as 'e' but execute always
  396.  
  397.           This  is  the  same  as 'e' but with the only difference that this
  398.         will  force  UUPOLL to execute the user command _always_, even if it
  399.         terminates  due  to  a  internal  error or any other conditions.  To
  400.         force the default user command to be executed always, specify `-E' -
  401.         not `-E ""' because this will indicate `no user command'.
  402.  
  403.     n  notify user if session fails
  404.  
  405.           If  you specify this option and the polling session fails due to a
  406.         restriction  timeout or maximal number of retries the given user (or
  407.         per  default  `postmaster')  will  be notified about this.  The user
  408.         will receive a message like the following:
  409.  
  410.         | From UUPOLL-DAEMON Fri, 12 Jun 1992 22:23:40 +0200
  411.         | Return-Path: <UUPOLL-DAEMON>
  412.         | Received: by angle.muc.sub.org (\/<>\/ SmailAmiga 1.02j21)
  413.         |       id <m0lwK20-00002Qc>; Fri, 12 Jun 1992 22:23:40 +0200
  414.         | Message-Id: <m0lwK20-00002Qc@angle.muc.sub.org>
  415.         | Date: Fri, 12 Jun 1992 22:23:40 +0200
  416.         | From: UUPOLL-DAEMON@angle.muc.sub.org (UUCP Admin Subsystem)
  417.         | To: postmaster
  418.         | Subject: brumuc: polling failed
  419.         | X-Status: OR
  420.         |
  421.         | [autogenerated message]
  422.         |
  423.         | Local Time  : Fri Jun 12 22:23:36 1992
  424.         | Remote Host : brumuc
  425.         | Status      : polling failed
  426.         |
  427.         | --
  428.         | UUPOLL-DAEMON
  429.  
  430.     a  always poll - ignore last status
  431.  
  432.           This  forces  UUPOLL to start the polling procedure independend of
  433.         its  status  of the last session, i.e.  whether the last session was
  434.         successful or not.
  435.  
  436.           UUPOLL  sets  a enviroment variable (`UUPOLL.{hostname}') for each
  437.         host  automatically  after  a  polling  session  to  `SUCCESSFUL' or
  438.         `FAILED'  according  to  the  results  of the polling procedure.  At
  439.         startup  UUPOLL  checks  for  this  variable and does nothing if its
  440.         status  is  already  `SUCCESSFUL'.   But  if you specify this option
  441.         UUPOLL treats it always as `FAILED' and starts the polling procedure
  442.         even if the last one was already successful.  This should be used in
  443.         the  following  context  with  a  `crontab',  e.g.  here is `angle's
  444.         crontab:
  445.  
  446.           :
  447.           | 05  03  *   *   *       trimsys
  448.           | 10  03  28  *   *       autoinpaths angle mailto
  449.         ... pathsurvey@stasys.sta.sub.org
  450.           | 10  03  *   *   *       uppub
  451.           | 15  03  *   *   *       bms batch
  452.           | 20  03  *   *   *       batchsite cyvaned
  453.           | 25  03  *   *   *       gettyctl run on
  454.           | 40  03  *   *   *       uupoll -p -c0 -d120 -r3 -t20 -Scyvaned
  455.         ... -u " -7 -p3"
  456.           | 45  03  *   *   *       gettyctl off shut
  457.           | 50  03  *   *   *       batchsite brumuc
  458.          !| 00  04  *   *   *       uupoll -a -c1 -d120 -r6 -t30 -Sbrumuc
  459.         ... -u " -7 -p3" -e poll.workup
  460.           | 55  04  *   *   *       uumsg.daily
  461.           | 59  04  *   *   *       shutdown
  462.           :
  463.  
  464.           :
  465.          !| 00  08  *   *   *       uupoll -c1 -d120 -r6 -t60 -Sbrumuc
  466.           | 59  08  *   *   *       shutdown
  467.           :
  468.  
  469.           As  you  can  see,  the cron-daemon starts a polling session every
  470.         morning  at  four o'clock to connect to host `brumuc'.  As mentioned
  471.         above,  `angle'  has  a  reserved polling time at host `brumuc' from
  472.         four  to  half  past  four.  So UUPOLL is started with a restriction
  473.         time  of  30  minutes  (of  course  this  could be left, then UUPOLL
  474.         calculates  these  60  minutes out of the UULIB:l.sys entry for host
  475.         `brumuc).
  476.  
  477.           UUPOLL  now connects to `brumuc' with a maximum of 30 minutes.  If
  478.         there  would  be  more  data  than  `angle'  could  get in this time
  479.         interval,  UUPOLL breaks at half past four.  Then the status of this
  480.         polling  session  is  set  to  `FAILED' which lets the second UUPOLL
  481.         (started  at  eight o'clock) to go on with the transmission.  If the
  482.         first sesssion would be successful the second UUPOLL does nothing!
  483.  
  484.     p  poll only if pending work
  485.  
  486.           This option indicates UUPOLL to poll only if there is pending work
  487.         (i.e.   spooled  files) for the host.  Per default (or if the option
  488.         `-p0'  is given) UUPOLL does no such check.  If `-p{N}' is specified
  489.         UUPOLL  polls only if there are more or equal to N pending files for
  490.         the host.
  491.  
  492.         This option was introduced for `DEMAND' pollings.
  493.  
  494.     c  check for already spawned UUCICO
  495.  
  496.           This  option  was  introduced  for  special  situations.  It tells
  497.         UUPOLL  to  check  for  a running UUCICO process at startup.  Have a
  498.         look again at my crontab:
  499.  
  500.           :
  501.           | 25  03  *   *   *       gettyctl run on
  502.           | 40  03  *   *   *       uupoll -p -c0 -d120 -r3 -t20 -Scyvaned
  503.         ... -u " -7 -p3"
  504.           | 45  03  *   *   *       gettyctl off shut
  505.           :
  506.  
  507.           First,  the background:  the connection `angle' <-> `cyvaned' is a
  508.         daily  DEMAND  connection,  i.e.  if one of these hosts have pending
  509.         work,  it  polls  the  other.  To implement this connection we could
  510.         give  `cyvaned'  a  time from 03:00-03:30 to poll `angle' and a time
  511.         from  03:30-04:00  for `angle' to poll `cyvaned'.  Then at each host
  512.         UUPOLL  is  started with the `-p' option (see above) to poll only if
  513.         pending  work.   This would work fine, because if `cyvaned' had work
  514.         it  polls angle first, then `angle' will not poll back even if there
  515.         _was_ work, but will poll if `cyvaned' hadn't polled.
  516.  
  517.           The  only  "problem"  is,  that  we  had to reserve two(!) polling
  518.         times!  To  solve  this  "problem", we can use the `-c0' option from
  519.         UUPOLL:
  520.  
  521.           We  reserve  only  one  polling  time  from 03:30 for both polling
  522.         directions.   As you can see from 03:25-03:45 the GETTY command runs
  523.         to observe the phoneline and to answer incoming calls.  This is done
  524.         because  `cyvaned'  tries  always  to  start a connection first.  So
  525.         `cyvaned'  has  15  (actually  20  but  it  start dialing `angle' at
  526.         03:30!)  minutes  to dial `angle'.  If `cyvaned' didn't poll `angle'
  527.         (due to no pending work) and `angle' has pending work, `angle' polls
  528.         `cyvaned'  ten  minutes after the polling time interval starts (i.e.
  529.         03:40).   If  `cyvaned'  polls  `angle',  `angle'  (i.e.   UUPOLL on
  530.         `angle') had to now at 03:40 if it should poll back or not.
  531.  
  532.           The  `-p' option does a goof work only, if the connection would be
  533.         less  than  10  minutes (i.e.  the connection is finished at 03:40).
  534.         If  the  connection  still  in  process, this doesn't work.  But the
  535.         '-c0'  option  tells  UUPOLL  to  abort immediately after startup if
  536.         there  is  still  a  connection active (i.e.  a still running UUCICO
  537.         process).
  538.  
  539.           Another  feature  is  `-c1':   This tells UUPOLL to break a UUCICO
  540.         process  which  is  still  active at UUPOLL startup.  This is useful
  541.         when  you  want  your  system  to  poll out even if there is still a
  542.         active  incoming polling process (i.e.  a host is still polling your
  543.         system).
  544.  
  545.     j  switch/set job control status
  546.  
  547.           UUPOLL  can  be  disabled  via  this  option, i.e.  you can forbid
  548.         UUPOLL  to  do  anything  (except  host  status) until you permit it
  549.         again.   `-j'  switches  the  status from `disabled' to `enabled' or
  550.         vice versa.  `-j0' disables, `-j1' enables UUPOLL.
  551.  
  552.         This option was introduced for crontab interventions.
  553.  
  554.     i  current host status information
  555.  
  556.           This  option tells UUPOLL not to poll actually but to give you the
  557.         current  host status.  This function can be used in conjunction with
  558.         `-s'  to  display  a  particular  host  status.   You can specify an
  559.         argument  to this option:  "0" for short host status (without the 72
  560.         hour  chart)  and "1" for long hoststatus.  Specifing no argument to
  561.         `-i' acts like `-i0', i.e.  the short hoststatus is displayed.
  562.  
  563.         The short host status will look like the following:
  564.  
  565.           | UUPoll Host Status on angle          Sat Jun 06 20:24:28 1992
  566.           |
  567.           | remote host  : brumuc
  568.           | last polling : failed
  569.           |
  570.           | ACTIVE polling time intervall [#]    NEXT polling time intervall
  571.           | from Sat/19:00 to Sat/20:30          from Sun/04:00 to Sun/04:50
  572.           | total time 01:30, remaining 00:06    total time 00:50, in 07:36
  573.  
  574.         The long host status will look like the following:
  575.  
  576.           | UUPoll Host Status on angle                        Sat Jun 0 ...
  577.           |
  578.           | remote host  : brumuc                                   [|]  ...
  579.           | last polling : failed                                   [.]
  580.           |                                                              ...
  581.           | 55 ||...||.||.#............||...||.||.|............||...||.|
  582.           | 50 ||...||.||.#............||...||.||.|............||...||.| ...
  583.           | 45 ||...||.||.#........|...||...||.||.|........|...||...||.|
  584.           | 40 ||..|||.||.#........|...||..|||.||.|........|...||..|||.| ...
  585.           | 35 ||..|||.||.#........|...||..|||.||.|........|...||..|||.|
  586.           | 30 ||..|||.||.#........|...||..|||.||.|........|...||..|||.| ...
  587.           | 25 ||..|||.|||#X.......|...||..|||.|||||.......|...||..|||.|
  588.           | 20 ||..|||.|||##.......|...||..|||.|||||.......|...||..|||.| ...
  589.           | 15 ||..|||.|||##.......|...||..|||.|||||.......|...||..|||.|
  590.           | 10 ||....|..||##.......|...||....|..||||.......|...||....|.. ...
  591.           | 05 ||....|..||##.......|...||....|..||||.......|...||....|..
  592.           | 00 ||....|..||##.......|...||....|..||||.......|...||....|.. ...
  593.           |                ^
  594.           |    890123456789012301234567890123456789012301234567890123456 ...
  595.           |      1         2   Sun       1         2   Mon       1
  596.           |                                                              ...
  597.           | ACTIVE polling time intervall [#]    NEXT polling time inter
  598.           | from Sat/19:00 to Sat/20:30          from Sun/04:00 to Sun/0 ...
  599.           | total time 01:30, remaining 00:05    total time 00:50, in 07
  600.  
  601.           As you can see this will give you a full overview of all essential
  602.         polling information.  You will get
  603.  
  604.         - the local time (upper right hand corner)
  605.         - the remote host and its last polling status
  606.         - a 72 hour polling time chart (hours on x-axis, minutes on y-axis)
  607.         - information about the time interval which is currently active
  608.         - information about the next permitted time interval
  609.  
  610.         Look a while at this output to understand it and you will love it!
  611.  
  612.     x  number of debuglevel
  613.  
  614.           Because  UUPOLL  does  no  console  output  (except  polling  time
  615.         violation    message   or   host   status)   until   you   set   the
  616.         Runtime-Debugging  you  can  specify  the debuglevel (0-9) with this
  617.         option.   A  level  of zero means no debugging info, a level of nine
  618.         means full debug output to the console.
  619.  
  620.     v  version info
  621.     ?  usage info
  622.  
  623.           Specify  one  of  these  options  to  let  UUPOLL print either the
  624.         version page or the usage page to the console.
  625.  
  626.  
  627.                                     EXAMPLES
  628.  
  629.     $ uupoll
  630.  
  631.           This  is  the  simplest  way  to  use UUPOLL.  It will extract the
  632.         hostname of UULIB:config, does no retries and delays, calculates its
  633.         restriction  timeout  to  the  current active time situation, spawns
  634.         UUCICO  via  'UUCICO -s{defaulthost} -7', does no modem setup, polls
  635.         only if the last polling has failed and gives no console output.
  636.  
  637.     $ uupoll -i -scyvaned
  638.  
  639.           This  will  display  the host status for `cyvaned'.  No polling is
  640.         actually done.
  641.  
  642.     $ uupoll -a -r10 -scyvaned
  643.  
  644.           This  will  poll host `cyvaned', ignore the current host status to
  645.         and do a maximum of 10 retries if it couldn't connect.
  646.  
  647.     $ uupoll -a -p -Sbrumuc
  648.  
  649.           Now  UUPOLL  would  always  poll host `brumuc', even if there is a
  650.         reserved  time  currently  active  (`-S')  or if the last status was
  651.         successful  (`-a'),  but  not  if  there is no pending work for this
  652.         site.
  653.  
  654.     $ uupoll -a -r10 -p3 -d120 -t30 -scyvaned -e poll.workup
  655.  
  656.           Now  UUPOLL  would  poll  host  `cyvaned' idependently of the last
  657.         session,  but  only  if at least three command files are waiting for
  658.         `cyvaned'  in  the  spool  directory.   UUPOLL has thirty minutes to
  659.         operate,  should  do  a  maxium of ten retries and waits two minutes
  660.         between each retry.  After completing the polling session successful
  661.         UUPOLL  should  execute  the  script  file `poll.workup' (script bit
  662.         set!).
  663.  
  664.  
  665.                                    THANKS
  666.  
  667.     are going to the following people (in alphabetic order):
  668.  
  669.     Stephen Baker <sbaker@starl.miami.fl.us>
  670.     Jeff Van Epps <lordbah@amusing.bah.rochester.ny.us>
  671.     Marc Laukien <ml@brumuc.muc.sub.org>
  672.     Thomas Lotterer <joedust@cyvaned.cyvaned.sub.org>
  673.     Henning Schmiedehausen <barnard@forge.erh.sub.org>
  674.  
  675.  
  676.                                 MAILING ADDRESS
  677.  
  678.       If  you  have  any questions, incitements, comments, criticisms or bug
  679.     reports, please send it to:
  680.  
  681.                          uupoll-m@angle.muc.sub.org
  682.                   ...!smurf.sub.org!brumuc!angle!uupoll-m
  683.  
  684.  
  685.                                            Ralf S. Engelschall
  686.                                            rse@angle.muc.sub.org
  687.  
  688.