home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / events.doc < prev    next >
Text File  |  2001-03-27  |  8KB  |  229 lines
  1. 15 November 1999. Daniel Hellerstein (danieh@crosslink.net)
  2.  
  3.                   The SRE-http event monitor.     
  4.  
  5. Abstract:
  6.    The SRE-http event monitor is used to track, and respond to,
  7.    the status of the system.  Using temporary files and event semaphores,
  8.    external processes can use the event monitor to communicate with and 
  9.    control GoServe and  SRE-http.
  10.  
  11.                         ------------------
  12.  
  13. I. Introduction
  14.  
  15. The SRE-http event monitor is used to monitor a variety of events. If one
  16. of these events occurs, a number of actions can be taken.  These events can
  17. be set by external processes, or by an administator, as a means of indirectly
  18. controlling GoServe and SRE-http.  
  19.  
  20. For example:
  21.   * An external process could set an event semaphore when a shutdown is
  22.     needed.  The event monitor can detect this event semaphore, and
  23.     cleanly close GoServe.
  24.  
  25.   * An administrator can create a temporary file which will signal
  26.     GoServe to suspend (to refuse further connections), and then create
  27.     a second file to tell GoServe to resume.
  28.  
  29.   * SRE-http can run an external procedure on a scheduled basis, and then
  30.     run a second procedure if this procedure sets a simple flag.
  31.  
  32. Note that the event monitor complements SRE-http addons (such as RESTART), 
  33. and also complements the SRE-http scheduler (as described in SCHEDULE.DOC).  
  34. However, in many cases, the event monitor will be much easier to use.
  35.  
  36.                 ---------------------------------
  37.  
  38. II. Enabling events
  39.  
  40. To enable these events, one must set the EVENTS_CHECK parameter 
  41. (in INIT_STA.80), and modify the EVENTS.CFG file.
  42.  
  43. EVENTS_CHECK:  
  44.    Sets the frequency (in minutes) that SRE-http will check events.
  45.    To never check events, set EVENT_CHECK=0
  46.    Examples:
  47.        EVENT_CHECK=0
  48.        EVENT_CHECK=15
  49.  
  50. EVENTS.CFG
  51.    EVENTS.CFG should be in the CFGS\ directory of your GoServe working
  52.    directory.  EVENTS.CFG conists of multi-line "mime-like" records, 
  53.    where each record indicates the event to look for, and what do 
  54.    do should this event be found.
  55.         
  56. Assuming that EVENTS_CHECK<>0, SRE-http will check EVENTS.CFG every
  57. EVENTS_CHECK minutes. Alternatively, you can post the 
  58. \SEM32\SREF_80_EVENT_CHECK event semaphore to force SRE-http to immediately
  59. check events (if you are using a port other then 80, replace 80 with the 
  60. port you are using).
  61.  
  62.                 ---------------------------------
  63.  
  64.  
  65. III. Structure of EVENTS.CFG
  66.  
  67. EVENTS.CFG consists of multi-line records, with each record seperated by a
  68. blank line. Each line of these records will have a "mine-like" structure,
  69. of the form:
  70.   field: arg1 arg2
  71.  
  72. Notes:
  73.   *  Event records are seperated by blank lines.
  74.   *  Lines beginning with ; are comments, and are ignored.
  75.   *  FIELD and ARG1  are always case insensitive
  76.   *  Alive events are executed in order of appearance.
  77.  
  78.  
  79. Three "field" values are recognized: TYPE, ACTION, and RETAIN.
  80.  
  81. TYPE:
  82.   TYPE describes the type of event to look for. ARG1 specifies
  83.   what "type" of event; and may take one of three values: FILE,
  84.   SEMAPHORE, and PROCEDURE>
  85.  
  86.     FILE: check for the existence of a specified file
  87.  
  88.           The syntax is:  TYPE: FILE TEMP_FILENAME
  89.  
  90.       where:
  91.           Temp_filename:  a fully qualified name of a "temporary file"
  92.  
  93.       If this file exists, then the event has occurred.
  94.  
  95.     SEMAPHORE: check for the existence of a specified event semaphore
  96.  
  97.           The syntax is:  TYPE: SEMAPHORE EVENT_SEM
  98.  
  99.        where:
  100.            Event_sem: a valid OS/2 event semaphore.
  101.  
  102.        If the semaphore exists and is posted, then the event has occurred.
  103.  
  104.     PROCEDURE: run an external REXX procedure, and check its returned value     
  105.  
  106.           The syntax is:  TYPE: PROCEDURE REXXPROC ANARG
  107.        
  108.        where: 
  109.            Rexxproc: a fully qualified filename, this file must contain
  110.                      an external REXX procedure. 
  111.            Anarg: an optional argument (possibly containing spaces)
  112.  
  113.        This procedure will be called, with anarg provided as a single argument.
  114.        If this procedure returns a 1, then the event has occurred.
  115.        Otherwise, the event has NOT occurred (note that the procedure must 
  116.        return something).
  117.   
  118.   Notes:
  119.      *  Event sempahores MUST begin with \SEM32\
  120.      *  You can use F, S, or P as a shorthand for FILE, SEMAPHORE and
  121.         PROCEDURE (respectively)
  122.      *  By default, a temp_filename is deleted, and an event_sem
  123.         is reset. This can be modified by using a RETAIN: entry (see below)
  124.      *  An external rexxproc can use GoServe and SRE-http functions to check 
  125.         the status of the server.
  126.      *  The rexxproc file can be anywhere on your system (SRE-http will first
  127.         load into macrospace, and the run it).
  128.  
  129. ACTION:
  130.   ACTION describes what to do if the event (specified in the TYPE: entry)
  131.   occurs. Several kinds of ACTIONS are recognized: RESET, SHUTDOWN,
  132.   SUSPEND, RESUME, INTERPRET, CALL, EXEC.
  133.  
  134.      RESET: reset sre parameters (re-read parameter files)
  135.  
  136.      SHUTDOWN: shutdown GoServe (using the GoServe CLOSE directive)
  137.  
  138.      SUSPEND: refuse further connections
  139.  
  140.      RESUME: cancel a SUSPEND (start accepting further connections)
  141.  
  142.      INTERPRET zzz: "interpret" some REXX code
  143.         where: zzz is "interpretable" REXX code, which can span
  144.                multiple lines
  145.  
  146.      CALL rexxproc anarg: call an external REXX procedure
  147.          where:
  148.            rexxprox: a fully qualified filename that contains a REXX procedure
  149.               Anarg: an optional argument (possibly containing spaces)
  150.  
  151.           REXXPROC will be called with anarg as an optional argument. REXXPROC
  152.           can return anything (it must return something) -- the return value
  153.           is ignored.
  154.  
  155.      EXEC aprogram: run an executable program, or a batch file
  156.          where:
  157.             aprogram: a valid OS/2 command, such as the name of an executable 
  158.                       program.
  159.  
  160. RETAIN:
  161.   Retain is used to suppress removal of a TEMP_FILENAME or an EVENT_SEM.
  162.  
  163.   RETAIN: YES  (or RETAIN: 1)
  164.          Do NOT reset a semaphore, and do not delete a temporary file
  165.  
  166.   RETAIN:NO (or RETAIN: 0)
  167.          Reset a semaphore, and delete a temporary file
  168.  
  169.   The default is RETAIN: NO.
  170.  
  171.                 ---------------------------------
  172.  
  173. IV. Example of an EVENTS.CFG file
  174.  
  175.   ; see below for a sample of a "shutdown GoServe" REXX program, that
  176.   ; works with this event entry
  177.   Type: SEMAPHORE \SEM32\SHUTDOWN_1
  178.   Action: shutdown
  179.  
  180.   ; these next three tell SRE-http to look for a "flag file", and 
  181.   ; if found:
  182.   ;   i) temporarily suspend (refuse further connections)
  183.   ;  ii) do a (possibly time-consuming) "cleanup"
  184.   ; iii) resume (accept further connections)
  185.   Type: F e:\goserve\flags\flag.1
  186.   Action: SUSPEND
  187.   Retain: Yes
  188.  
  189.   Type: F e:\goserve\flags\flag.1
  190.   Action: Call e:\goserve\cleanup.cmd 
  191.   Retain: Yes
  192.  
  193.   ; note the use of "RETAIN:" in the two preceeding entries.
  194.   Type: F e:\goserve\flags\flag.1
  195.   Action: resume
  196.   
  197.  
  198.   ; Be sure to end each "line", of a block of interpretable REXX code, 
  199.   ; with a semi-colon
  200.   Type: Procedure check_time
  201.   Action: interpret atime=time('n') ;
  202.             adate=date('n') ;
  203.             call pmprintf("Today's date is: "||atime||' '||adate) 
  204.  
  205.                 ---------------------------------
  206.  
  207. V. Example of a REXX program to shutdown GoServe
  208.  
  209. In conjunction with the first entry in the sample EVENTS.CFG file, this program
  210. can be used to shutdown your server.
  211.  
  212.    /* Signal GoServe/SRE-http to shutdown */
  213.  
  214.    /* 1) create a semaphore */
  215.    foo=eventsem_create('\SEM32\SHUTDOWN_1')
  216.  
  217.    /* 2) Post it */
  218.    foo=eventsem_post('\SEM32\SHUTDOWN_1')
  219.  
  220.    /* 3) Optional -- post a semaphore to force SRE-http to shutdown
  221.       immediately. If you do not include this line, then SRE-http may
  222.       wait "EVENT_CHECK" minutes before checking this shutdown event. */
  223.  
  224.    foo=eventsem_post('\SEM32\SREF_80_EVENT_CHECK')
  225.  
  226.  
  227. .end of documentation
  228.  
  229.