DP Tool Club 24/CD_ASCQ_24_0995.iso/vrac/semaf003.zip/SEMAFORE.DOC

Text File | 1995-07-01 | 15KB | 327 lines

                          Semaphore Utility, Revision 3

                                  Written by :
                Marco Miltenburg, 2:512/64@fidonet, [e-mail]



    ────────────────────────────────────────────────────────────────────────
    In no event shall  Marco Miltenburg be liable to you  or anyone else for
    any  special, incidental, consequential, indirect or similar damages due
    to the use  of this program even if one of our support-sites has advised
    you to use the program  in a special way. The program is  provided as it
    is, and you use  it at your  own risk. All brands  and product names  in
    this  documentation are  trademarks or  registered  trademarks of  their
    respective holders.
    ────────────────────────────────────────────────────────────────────────


    WHAT IS IT ?
    ════════════────────────────────────────────────────────────────────────
    If you don't know what semaphore files are, you probably don't need this
    little utility. It's  written to make  writing batchfiles for  MultiLine
    BBS systems somewhat easier.

    SEMAFORE is a little utility that can create, delete and touch semaphore
    files. In  addition it can  also wait (configurable maximum  time) for a
    semaphore file  to exist or to clear. Last  but not least, it can report
    through an errorlevel if the specified semaphore file exists or not.

    Creation,  updating  and  deleting  of  the  semaphore   files  is  done
    according to the guidelines provided  by Joaquim Homrighausen (in his FD
    2.20 Developers  Package), author  of the  well  known FrontDoor  mailer
    which  makes extensive  use  of semaphore  files.  This assures  maximum
    compatible with a variety of mailers, BBS systems, operating systems and
    NOS.

    SEMAFORE  is multitasker aware. This means  that when it's waiting for a
    semaphore file to clear or to appear, it will return time-slices back to
    the operating system or multitasker. Currently supported systems are :

      Windows/Std 3.x and higher
      Windows/386 2.x and higher
      OS/2 2.x and OS/2 Warp
      DESQview and DESQview/X


    USAGE
    ═════───────────────────────────────────────────────────────────────────
    Usage of SEMAFORE is very easy. If  started without any command, it will
    display the following help screen :

     SEMAFORE, Rev. 3   Multi-Line BBS Semaphore Utility   Freeware!
     Copyright (C) 1994-1995, Marco A.J. Miltenburg. All rights reserved.

     Usage :

       SEMAFORE <action>[<action>] <filename> [<waittime>]|[<waittime>s]

     Action  :  +  Create or touch semaphore.
                -  Delete semaphore.
                *  Create when not exist, return errorlevel 1 when created.
                !  Wait until semaphore exist.
                ?  Wait until semaphore is cleared (removed).
                &  If semaphore exists, return errorlevel 1.
                %  If semaphore doesn't exist, return errorlevel 1.

     Filename:  Full path and filename of semaphore file.

     Waittime:  Maximum time to wait (optional for use with ! and ?).
                If the time has expired, exit with errorlevel 1. If followed
                by an 's' the time is in seconds, otherwise minutes.

    SEMAFORE requires at least two options. The first is one or more actions
    and a semaphore  filename. The third waittime option  is always optional
    and assumed zero if not given.


    ─  Creating Semaphores
    ──────────────────────
    Creating  a semaphore file  can be done  with the  following command (an
    example) :

      SEMAFORE + S:\SEMA\FD\FDFREEZE.ALL

    This  will create  the semaphore  S:\SEMA\FD\FREEZE.ALL.  If it  already
    exists, it will only touch the date/time of the semaphore.


    ─  Deleting Semaphores
    ──────────────────────
    Deleting  a semaphore file  can be done  with the  following command (an
    example) :

      SEMAFORE - S:\SEMA\FD\FDFREEZE.ALL

    This  will delete the  semaphore S:\SEMA\FD\FDFREEZE.ALL. If  it doesn't
    exist,  SEMAFORE will simply ignore  the command and return immediately.
    No error message  or whatsoever is displayed.  When deleting semaphores,
    you can also use wildcards to match multiple semaphores, e.g. :

      SEMAFORE - S:\SEMA\FD\FDFREEZE.*

    This will delete all FDFREEZE semaphore files.


    ─  Create Semaphore Only When It Doesn't Exist Yet
    ──────────────────────────────────────────────────
    The * option  is an extended version  of the + option.  This option will
    create the specified semaphore file only when it doesn't exist yet. When
    it's created,  it will exit  with errorlevel 1, otherwise  errorlevel 0.
    This is useful  when you  want to check  for a semaphore  file and  only
    create it when it doesn't exist already  (no touch). The following is an
    example on how to use this option :

      SEMAFORE * S:\SEMA\TOSSMAIL
      If Errorlevel 1 Goto TossMail

    This will create S:\SEMA\TOSSMAIL only when the TOSSMAIL semaphore isn't
    present already. When it's created, the batchfile will continue at label
    'TossMail'.  This makes sure that mail is only tossed when the semaphore
    is created by  the current task, preventing multiple  tasks from tossing
    mail at the same time.


    ─  Wait Until Semaphore Exists
    ──────────────────────────────
    In  addition  to  these basic  semaphore  operations,  SEMAFORE supports
    checking if  the  specified  semaphore  exists. If  it  doesn't  exists,
    SEMAFORE will wait till it exists. To narrow the change of  lockups, you
    can specify  a maximum time to wait.  If the specified semaphore doesn't
    appear in the  given time, SEMAFORE will display a warning and will exit
    with errorlevel 1. You can use this errorlevel in your batchfile to take
    care of this  situation. The following is an example on  how to use this
    option :

      SEMAFORE + S:\SEMA\FD\FDFREEZE.ALL
      SEMAFORE ! S:\SEMA\FD\FDFROZEN.2
      SEMAFORE ! S:\SEMA\FD\FDFROZEN.3
      SEMAFORE ! S:\SEMA\FD\FDFROZEN.4

    This fragment of a batchfile could be executed by line #1 of a MultiLine
    system  causing all  FrontDoor's on  the other 3  lines to  freeze until
    FDFREEZE.ALL is removed again (with SEMAFORE - S:\SEMA\FD\FDFREEZE.ALL).

    If you want to wait for a maximum of 2 hours for the semaphore FDALIVE.1
    to appear, you could use the following command :

      SEMAFORE ! S:\SEMA\FD\FDALIVE.1 120
      If Errorlevel 1 Echo Serious trouble on line #1 !!!

    The  maximum wait time  is normally  expressed in  minutes. If  you need
    shorter times or  times other than in minutes, add an 's' directly after
    the time to specify the waittime in seconds. E.g. :

      SEMAFORE ! S:\SEMA\FD\FDALIVE.1 100s
      If Errorlevel 1 Echo No respons within 100 seconds from line #1 !!!

    If this time expires, this example will display a warning message to the
    standard output device.


    ─  Wait Until Semaphore Is Cleared
    ──────────────────────────────────
    If you want to wait for  a specified semaphore to be cleared  (removed),
    you can use the following command :

      SEMAFORE ? S:\SEMA\HOLDLINE.1

    SEMAFORE will wait till the  semaphore HOLDLINE.1 is removed (by another
    line or anything else).  To wait a maximum of 15 minutes,  you can add '
    15' to the above commandline, like :

      SEMAFORE ? S:\SEMA\HOLDLINE.1 15
      If Errorlevel 1 Echo He, I'm already waiting for 15 minutes!

    If the semaphore  isn't cleared after 15 minutes, this example will echo
    a  message to  the  standard  output device.  This  option also  accepts
    wildcards in the semaphore filename to monitor multiple semaphore  files
    at the same time. E.g. :

      SEMAFORE ? S:\SEMA\LINEUP.* 500s
      If Errorlevel 1 Echo There are still lines running after 500 seconds!


    ─  Return Errorlevel
    ────────────────────
    Last but  not least SEMAFORE can  check if the  specified semaphore file
    exist  or not. If  it does,  it will  report an errorlevel  of 1.  If it
    doesn't exist, it will return with errorlevel 0. Example :

      SEMAFORE & S:\SEMA\FD\FDALIVE.1
      If Errorlevel 1 SEMAFORE + S:\SEMA\FD\FDXIT1.10

    The above piece  of batchfile will force  FrontDoor Task 1 to  exit like
    the user pressed ALT-Q  on the keyboard. However, the semaphore  is only
    created when Task 1 is up and running.

    The inverse of this option is the % command. This will force SEMAFORE to
    exit with errorlevel 1 when the semaphore does NOT exist, e.g. :

      SEMAFORE % S:\SEMA\FD\FDALIVE.1
      If Errorlevel 1 Echo FrontDoor Task 1 is not running

    Both & and % also accept wildcards in the semaphore filename.


    ─  Multiple Actions
    ───────────────────
    SEMAFORE can  handle multiple actions on  the semaphore file  at once in
    the same run. It will handle them  in the same order you present them on
    the commandline. A good example for it's use is :

      SEMAFORE &- S:\SEMA\NEWMAIL.ALL

    This means  that SEMAFORE  will check if  the NEWMAIL.ALL  semafore does
    exist. If  it does,  it will  exit with  errorlevel 1  but it  will also
    remove the semaphore  to be sure it  won't be processed twice.  This can
    ofcourse also be utilized as :

      SEMAFORE %+ S:\SEMA\SCANNOW.ALL

    which does the opposite. The following command is ofcourse nonsense :

      SEMAFORE +- S:\SEMA\WHATEVER.ALL

    but completly valid for SEMAFORE. In fact it will do exactly what it has
    been told and will create and remove the semaphore  file in one run. You
    may specify an unlimited number of actions, e.g. :

      SEMAFORE -!- S:\SEMA\NOTIFY.1

    which  might  be  usefull. It  will  always  wait for  a  fresh NOTIFY.1
    semaphore. If it already exists when SEMAFORE is started, it will remove
    it and wait for it to show up.

    Another possiblity that comes to mind is :

      SEMAFORE +?- S:\SEMA\SYNCH.NOW 2

    which will create SYNCH.NOW. After that  it will wait for 2 minutes  for
    SYNCH.NOW to  clear so it knows in which state the other line is. If the
    semaphore is not  cleared within 2 minutes,  it will be also  be removed
    but no errorlevel will be reported.

    As you  can see,  you can  ease your  batchfile a  lot with  this little
    utility. Of course it can also  be done with standard DOS commands,  but
    this normally requires  more lines and continuous  execution and reading
    of  the batchfile by COMMAND.COM when waiting  for a semaphore to appear
    or clear  for example. SEMAFORE  will only  check once every  second and
    will  return timeslices  to  the above  mentioned multitaskers/operating
    systems. This speeds up processing in other tasks.


    FDOPT
    ═════───────────────────────────────────────────────────────────────────
    SEMAFORE supports the FDOPT environment  variable. It will recognize the
    following options :

    FORCEINT28     By default, SEMAFORE  uses the DPMI mechanism  to release
                   timeslices under OS/2  and Windows (FDOPT=FORCEDPMI).  By
                   using this option, SEMAFORE will  issue INT 28 calls when
                   returning   timeslices    when   running    under   these
                   multitaskers / operating systems.

    FORCECOMMIT    This will  force SEMAFORE  to use  the commit  call. This
                   will update the directory entry of  the semaphore on disk
                   every time is has been changed.

    NOCOMMIT       By  default SEMAFORE will use  the normal commit call. If
                   this   option  is   specified,  SEMAFORE   will  use   an
                   alternative way to commit changes.

    NOMULD         Prevents SEMAFORE  from auto-detecting the  multitasker /
                   operating  system.  No timeslices  will be  returned when
                   SEMAFORE is waiting.


    In contradiction  to FrontDoor, these  options can only  be set  via the
    FDOPT environment variable, NOT on  the commandline. All unknown options
    in the FDOPT environment variable are ignored.


    FINAL NOTE
    ══════════──────────────────────────────────────────────────────────────
    Almost  all of  the above  examples show  FrontDoor semaphore  files. Of
    course SEMAFORE can be used with other packages as well, but I just like
    FrontDoor, so I took that as  an example. I've tested SEMAFORE on  2 BBS
    systems  (6  lines totally)  of  which  I'm sysop.  It  didn't  show any
    compatibility problems with RemoteAccess 2.0x/SW/PRO, FrontDoor 2.20c.mL
    (and higher), Novell Netware 3.11  to 4.1, Lantastic/AI 5.0, All version
    higher then  3.30 of MS-DOS, DESQview 2.62, Windows 3.10 and Windows for
    Workgroups 3.11. It works for me, so it should work for you.

    SEMAFORE has been  written by Marco Miltenburg  (2:512/64@fidonet) using
    Borland Pascal  7.0 for  DOS.  I have  written it  because there  wasn't
    anything else  on the  market with  the features  I wanted  it to  have.
    SEMAFORE is freeware. You don't have to  register it, nor do you have to
    pay me for using it. However, I like getting money on my bankaccount, so
    if you need to get rid of some, please mail me :-). I  also like to here
    from  people that  are using it  with or  without success. Feel  free to
    contact me at the following system :

      Public Board MultiLine
      Location: Driebergen, The Netherlands
      Line #1 : [phone] - USRobotics DS/HST V.Everything with V.34+
      Line #2 : [phone] - USRobotics DS/HST V32Bis, HST
      FidoNet : 2:512/64 (Line #1)
                2:512/364 (Line #2)


    CREDITS
    ═══════─────────────────────────────────────────────────────────────────
    Thanks to numerous people who  contacted me with suggestions and reports
    how  the use  SEMAFORE. Also  thanks to  Joaquim Homrighausen  and Bruce
    Bodger for hatching this utility in SDSFRONT.

    DESQview         Copyright QuarterDeck Office Systems.
    FrontDoor        Copyright Joaquim Homrighausen, Absolute Solutions.
    Lantastic        Copyright Artisoft, Inc.
    MS-DOS           Copyright Microsoft Corporation.
    Novell Netware   Copyright Novell Inc.
    OS/2             Copyright IBM Corporation.
    RemoteAccess     Copyright Andrew Milner, Wantree Development.
    Borland Pascal   Copyright Borland International, Inc.
    Windows          Copyright Microsoft Corporation.