home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / BBS / SEMAF002.ZIP / SEMAFORE.DOC < prev    next >
Text File  |  1994-11-21  |  12KB  |  258 lines
  1.  
  2.  
  3.                           Semaphore Utility, Revision 2
  4.  
  5.                                   Written by :
  6.                        Marco Miltenburg, 2:512/64@fidonet
  7.  
  8.  
  9.     ────────────────────────────────────────────────────────────────────────
  10.     In no event shall  Marco Miltenburg be liable to you or  anyone else for
  11.     any  special, incidental, consequential, indirect or similar damages due
  12.     to the use of this program even if one of our  support-sites has advised
  13.     you  to use the program in a special  way. The program is provided as it
  14.     is, and you  use it at your  own risk. All  brands and product names  in
  15.     this  documentation are  trademarks or  registered  trademarks of  their
  16.     respective holders.
  17.     ────────────────────────────────────────────────────────────────────────
  18.  
  19.  
  20.     WHAT IS IT ?
  21.     ════════════────────────────────────────────────────────────────────────
  22.     I  don't like writing  documentation, so  I'll make  this brief.  If you
  23.     don't know what semaphore files are, you probably don't need this little
  24.     utility.  It's  written to  make  writing batchfiles  for  MultiLine BBS
  25.     systems somewhat easier.
  26.  
  27.     SEMAFORE is a little utility that can create, delete and touch semaphore
  28.     files. In  addition it can  also wait (configurable maximum  time) for a
  29.     semaphore file  to exist or to clear. Last  but not least, it can report
  30.     through an errorlevel if the specified semaphore file exists or not.
  31.  
  32.     Creation,  updating  and  deleting  of  the  semaphore   files  is  done
  33.     according to the guidelines provided  by Joaquim Homrighausen (in his FD
  34.     2.20 Developers Package), author of the well know FrontDoor mailer which
  35.     makes extensive use of semaphore  files. This assures maximum compatible
  36.     with a variety of mailers, BBS systems, operating systems and NOS.
  37.  
  38.     SEMAFORE is multitasker aware.  This means that when it's waiting  for a
  39.     semaphore file to clear or to appear, it will return time-slices back to
  40.     the operating system or multitasker. Currently supported systems are :
  41.  
  42.       Windows/Std 3.x and higher
  43.       Windows/386 2.x and higher
  44.       OS/2 2.x and OS/2 Warp
  45.       DESQview and DESQview/X
  46.  
  47.  
  48.     USAGE
  49.     ═════───────────────────────────────────────────────────────────────────
  50.     Usage of SEMAFORE is very easy. If started without any command,  it will
  51.     display the following help screen :
  52.  
  53.       SEMAFORE, Rev. 2   Multi-Line BBS Semaphore Utility   Freeware!
  54.       Copyright (C) 1994, Marco A.J. Miltenburg. All rights reserved.
  55.  
  56.       Usage :
  57.  
  58.         SEMAFORE <action> <filename> [<minutes>]
  59.  
  60.       Action  :  +  Create or touch semaphore.
  61.                  -  Delete semaphore.
  62.                  *  Create when not exist, return errorlevel 1 when created.
  63.                  !  Wait until semaphore exist.
  64.                  ?  Wait until semaphore is cleared (removed).
  65.                  &  If semaphore exists, return errorlevel 1.
  66.                  %  If semaphore doesn't exist, return errorlevel 1.
  67.  
  68.       Filename:  Full path and filename of semaphore file.
  69.  
  70.       Minutes :  Maximum minutes to wait (optional for use with ! and ?).
  71.                  If the time has expired, exit with errorlevel 1.
  72.  
  73.     Creating a  semaphore file can  be done with  the following command  (an
  74.     example) :
  75.  
  76.       SEMAFORE + S:\SEMA\FD\FDFREEZE.ALL
  77.  
  78.     This  will create  the semaphore  S:\SEMA\FD\FREEZE.ALL.  If it  already
  79.     exists, it will only touch the date/time of the semaphore.
  80.  
  81.     Deleting a  semaphore file can  be done  with the following  command (an
  82.     example) :
  83.  
  84.       SEMAFORE - S:\SEMA\FD\FDFREEZE.ALL
  85.  
  86.     This  will delete the  semaphore S:\SEMA\FD\FDFREEZE.ALL. If  it doesn't
  87.     exist, SEMAFORE will simply  ignore the command and  return immediately.
  88.     No  error message or whatsoever is  displayed. When deleting semaphores,
  89.     you can also use wildcards to match multiple semaphores, e.g. :
  90.  
  91.       SEMAFORE - S:\SEMA\FD\FDFREEZE.*
  92.  
  93.     This will delete all FDFREEZE semaphore files.
  94.  
  95.     The * option is an  extended version of the  + option. This option  will
  96.     create the specified semaphore file only when it doesn't exist yet. When
  97.     it's created,  it will exit  with errorlevel 1, otherwise  errorlevel 0.
  98.     This  is useful  when you want  to check  for a semaphore  file and only
  99.     create it when it doesn't exist already  (no touch). The following is an
  100.     example on how to use this option :
  101.  
  102.       SEMAFORE * S:\SEMA\TOSSMAIL
  103.       If Errorlevel 1 Goto TossMail
  104.  
  105.     This will create S:\SEMA\TOSSMAIL only when the TOSSMAIL semaphore isn't
  106.     present already. When it's created, the batchfile will continue at label
  107.     'TossMail'. This makes  sure that mail is only tossed when the semaphore
  108.     is created by  the current task, preventing multiple  tasks from tossing
  109.     mail at the same time.
  110.  
  111.     In  addition  to  these basic  semaphore  operations,  SEMAFORE supports
  112.     checking  if  the  specified semaphore  exists.  If  it  doesn't exists,
  113.     SEMAFORE will wait till it exists. To narrow the change of  lockups, you
  114.     can  specify a  maximum  time (in  minutes) to  wait.  If the  specified
  115.     semaphore  doesn't appear  in the  given time,  SEMAFORE will  display a
  116.     warning and will exit with errorlevel 1. You can use this  errorlevel in
  117.     your batchfile  to take  care of  this  situation. The  following is  an
  118.     example on how to use this option :
  119.  
  120.       SEMAFORE + S:\SEMA\FD\FDFREEZE.ALL
  121.       SEMAFORE ! S:\SEMA\FD\FDFREEZE.2
  122.       SEMAFORE ! S:\SEMA\FD\FDFREEZE.3
  123.       SEMAFORE ! S:\SEMA\FD\FDFREEZE.4
  124.  
  125.     This fragment of a batchfile could be executed by line #1 of a MultiLine
  126.     system causing  all FrontDoor's on  the other  3 lines  to freeze  until
  127.     FDFREEZE.ALL is removed again (with SEMAFORE - S:\SEMA\FD\FDFREEZE.ALL).
  128.  
  129.     If you want to wait for a maximum of 2 hours for the semaphore FDALIVE.1
  130.     to appear, you could use the following command :
  131.  
  132.       SEMAFORE ! S:\SEMA\FD\FDALIVE.1 120
  133.       If Errorlevel 1 Echo Serious trouble on line #1 !!!
  134.  
  135.     The maximum  wait time is  expressed in  minutes. If this  time expires,
  136.     this  example will  display a  warning  message to  the standard  output
  137.     device.
  138.  
  139.     If you want to wait for  a specified semaphore to be cleared  (removed),
  140.     you can use the following command :
  141.  
  142.       SEMAFORE ? S:\SEMA\HOLDLINE.1
  143.  
  144.     SEMAFORE will wait till the  semaphore HOLDLINE.1 is removed (by another
  145.     line or anything else). To wait a  maximum of 15 minutes, you can add  '
  146.     15' to the above commandline, like :
  147.  
  148.       SEMAFORE ? S:\SEMA\HOLDLINE.1 15
  149.       If Errorlevel 1 Echo He, I'm already waiting for 15 minutes!
  150.  
  151.     If the semaphore isn't  cleared after 15 minutes, this example will echo
  152.     a  message to  the  standard  output device.  This  option also  accepts
  153.     wildcards in the semaphore filename to monitor multiple semaphore  files
  154.     at the same time.
  155.  
  156.     Last but not  least SEMAFORE can check  if the specified  semaphore file
  157.     exist  or not. If  it does,  it will  report an errorlevel  of 1.  If it
  158.     doesn't exist, it will return with errorlevel 0. Example :
  159.  
  160.       SEMAFORE & S:\SEMA\FD\FDALIVE.1
  161.       If Errorlevel 1 SEMAFORE + S:\SEMA\FD\FDXIT1.010
  162.  
  163.     The above piece  of batchfile will force  FrontDoor Task 1 to  exit like
  164.     the user pressed ALT-Q on  the keyboard. However, the semaphore is  only
  165.     created when Task 1 is up and running.
  166.  
  167.     The inverse of this option is the % command. This will force SEMAFORE to
  168.     exit with errorlevel 1 when the semaphore does NOT exist, e.g. :
  169.  
  170.       SEMAFORE % S:\SEMA\FD\FDALIVE.1
  171.       If Errorlevel 1 Echo FrontDoor Task 1 is not running
  172.  
  173.     Both & and % also accept wildcards in the semaphore filename.
  174.  
  175.     As you  can see,  you can  ease your  batchfile a  lot with this  little
  176.     utility. Of  course it can also be done  with standard DOS commands, but
  177.     this  normally requires more lines  and continuous execution and reading
  178.     of the batchfile by COMMAND.COM when  waiting for a semaphore to  appear
  179.     or clear  for example. SEMAFORE  will only  check once every  second and
  180.     will  return timeslices  to  the above  mentioned multitaskers/operating
  181.     systems. This speeds up processing in other tasks.
  182.  
  183.  
  184.     FDOPT
  185.     ═════───────────────────────────────────────────────────────────────────
  186.     SEMAFORE supports the FDOPT environment variable. It  will recognize the
  187.     following options :
  188.  
  189.     FORCEINT28     By default, SEMAFORE  uses the DPMI mechanism  to release
  190.                    timeslices under OS/2  and Windows (FDOPT=FORCEDPMI).  By
  191.                    using this option, SEMAFORE will issue INT 28  calls when
  192.                    returning   timeslices    when   running    under   these
  193.                    multitaskers / operating systems.
  194.  
  195.     NOCOMMIT       By  default,  SEMAFORE  will  commit  all  changes  to  a
  196.                    semaphore file directly  to disk. By using  this options,
  197.                    SEMAFORE will not force DOS to flush it's buffers.
  198.  
  199.     NOMULD         Prevents SEMAFORE from  auto-detecting the multitasker  /
  200.                    operating  system. No  timeslices will  be returned  when
  201.                    SEMAFORE is waiting.
  202.  
  203.     NORES          By  default, SEMAFORE will  expand paths of  filenames on
  204.                    network  and   CD-ROM  drives  to   true-pathnames  (e.g.
  205.                    \\SERVER\SYS etc...). This can be prevented by using this
  206.                    option   as  it  may  cause  trouble  with  some  network
  207.                    operating systems.
  208.  
  209.     In contradiction  to FrontDoor, these  options can only  be set  via the
  210.     FDOPT  environment variable, NOT on the commandline. All unknown options
  211.     in the FDOPT environment variable are ignored.
  212.  
  213.  
  214.     FINAL NOTE
  215.     ══════════──────────────────────────────────────────────────────────────
  216.     Almost  all of  the above  examples show  FrontDoor semaphore  files. Of
  217.     course SEMAFORE can be used with other packages as well, but I just like
  218.     FrontDoor, so I took  that as an example. I've tested  SEMAFORE on 2 BBS
  219.     systems  (5  lines totally)  of which  I'm sysop.  It's didn't  show any
  220.     compatibility problems with RemoteAccess 2.0x/SW/PRO, FrontDoor 2.20c.mL
  221.     (and higher), Novell Netware 3.11/3.12, Lantastic/AI 5.0, MS-DOS 5.0 and
  222.     6.2, DESQview  2.62, Windows  3.10 and Windows  for Workgroups  3.11. It
  223.     works for me, so it should work for you.
  224.  
  225.     SEMAFORE has been  written by Marco Miltenburg  (2:512/64@fidonet) using
  226.     Borland Pascal  7.0 for  DOS.  I have  written it  because there  wasn't
  227.     anything else  on the  market with  the features  I wanted  it to  have.
  228.     SEMAFORE is freeware. You  don't have to register it, nor do you have to
  229.     pay me for using it. However, I like getting money on my bankaccount, so
  230.     if you need to get  rid of some, please mail me :-). I also like to here
  231.     from people  that are  using it with  or without  success. Feel  free to
  232.     contact me at the following system :
  233.  
  234.       Public Board MultiLine
  235.       Location: Driebergen, The Netherlands
  236.       Line #1 : +31-3438-14125 - USRobotics DS/HST V.Everything with V.34
  237.       Line #2 : +31-3438-33602 - USRobotics DS/HST V32Bis, HST
  238.       FidoNet : 2:512/64 (Line #1)
  239.                 2:512/364 (Line #2)
  240.  
  241.  
  242.     CREDITS
  243.     ═══════─────────────────────────────────────────────────────────────────
  244.     Thanks to numerous people who  contacted me with suggestions and reports
  245.     how  the use  SEMAFORE. Also  thanks to  Joaquim Homrighausen  and Bruce
  246.     Bodger  (nice  pictures by  the way  ;-)) for  hatching this  utility in
  247.     SDSFD.
  248.  
  249.     DESQview         Copyright QuarterDeck Office Systems.
  250.     FrontDoor        Copyright Joaquim Homrighausen, Absolute Solutions.
  251.     Lantastic        Copyright Artisoft, Inc.
  252.     MS-DOS           Copyright Microsoft Corporation.
  253.     Novell Netware   Copyright Novell Inc.
  254.     OS/2             Copyright IBM Corporation.
  255.     RemoteAccess     Copyright Andrew Milner, Wantree Development.
  256.     Borland Pascal   Copyright Borland International, Inc.
  257.     Windows          Copyright Microsoft Corporation.
  258.