15 November 1999. Daniel Hellerstein (danieh@crosslink.net) The SRE-http event monitor. Abstract: The SRE-http event monitor is used to track, and respond to, the status of the system. Using temporary files and event semaphores, external processes can use the event monitor to communicate with and control GoServe and SRE-http. ------------------ I. Introduction The SRE-http event monitor is used to monitor a variety of events. If one of these events occurs, a number of actions can be taken. These events can be set by external processes, or by an administator, as a means of indirectly controlling GoServe and SRE-http. For example: * An external process could set an event semaphore when a shutdown is needed. The event monitor can detect this event semaphore, and cleanly close GoServe. * An administrator can create a temporary file which will signal GoServe to suspend (to refuse further connections), and then create a second file to tell GoServe to resume. * SRE-http can run an external procedure on a scheduled basis, and then run a second procedure if this procedure sets a simple flag. Note that the event monitor complements SRE-http addons (such as RESTART), and also complements the SRE-http scheduler (as described in SCHEDULE.DOC). However, in many cases, the event monitor will be much easier to use. --------------------------------- II. Enabling events To enable these events, one must set the EVENTS_CHECK parameter (in INIT_STA.80), and modify the EVENTS.CFG file. EVENTS_CHECK: Sets the frequency (in minutes) that SRE-http will check events. To never check events, set EVENT_CHECK=0 Examples: EVENT_CHECK=0 EVENT_CHECK=15 EVENTS.CFG EVENTS.CFG should be in the CFGS\ directory of your GoServe working directory. EVENTS.CFG conists of multi-line "mime-like" records, where each record indicates the event to look for, and what do do should this event be found. Assuming that EVENTS_CHECK<>0, SRE-http will check EVENTS.CFG every EVENTS_CHECK minutes. Alternatively, you can post the \SEM32\SREF_80_EVENT_CHECK event semaphore to force SRE-http to immediately check events (if you are using a port other then 80, replace 80 with the port you are using). --------------------------------- III. Structure of EVENTS.CFG EVENTS.CFG consists of multi-line records, with each record seperated by a blank line. Each line of these records will have a "mine-like" structure, of the form: field: arg1 arg2 Notes: * Event records are seperated by blank lines. * Lines beginning with ; are comments, and are ignored. * FIELD and ARG1 are always case insensitive * Alive events are executed in order of appearance. Three "field" values are recognized: TYPE, ACTION, and RETAIN. TYPE: TYPE describes the type of event to look for. ARG1 specifies what "type" of event; and may take one of three values: FILE, SEMAPHORE, and PROCEDURE> FILE: check for the existence of a specified file The syntax is: TYPE: FILE TEMP_FILENAME where: Temp_filename: a fully qualified name of a "temporary file" If this file exists, then the event has occurred. SEMAPHORE: check for the existence of a specified event semaphore The syntax is: TYPE: SEMAPHORE EVENT_SEM where: Event_sem: a valid OS/2 event semaphore. If the semaphore exists and is posted, then the event has occurred. PROCEDURE: run an external REXX procedure, and check its returned value The syntax is: TYPE: PROCEDURE REXXPROC ANARG where: Rexxproc: a fully qualified filename, this file must contain an external REXX procedure. Anarg: an optional argument (possibly containing spaces) This procedure will be called, with anarg provided as a single argument. If this procedure returns a 1, then the event has occurred. Otherwise, the event has NOT occurred (note that the procedure must return something). Notes: * Event sempahores MUST begin with \SEM32\ * You can use F, S, or P as a shorthand for FILE, SEMAPHORE and PROCEDURE (respectively) * By default, a temp_filename is deleted, and an event_sem is reset. This can be modified by using a RETAIN: entry (see below) * An external rexxproc can use GoServe and SRE-http functions to check the status of the server. * The rexxproc file can be anywhere on your system (SRE-http will first load into macrospace, and the run it). ACTION: ACTION describes what to do if the event (specified in the TYPE: entry) occurs. Several kinds of ACTIONS are recognized: RESET, SHUTDOWN, SUSPEND, RESUME, INTERPRET, CALL, EXEC. RESET: reset sre parameters (re-read parameter files) SHUTDOWN: shutdown GoServe (using the GoServe CLOSE directive) SUSPEND: refuse further connections RESUME: cancel a SUSPEND (start accepting further connections) INTERPRET zzz: "interpret" some REXX code where: zzz is "interpretable" REXX code, which can span multiple lines CALL rexxproc anarg: call an external REXX procedure where: rexxprox: a fully qualified filename that contains a REXX procedure Anarg: an optional argument (possibly containing spaces) REXXPROC will be called with anarg as an optional argument. REXXPROC can return anything (it must return something) -- the return value is ignored. EXEC aprogram: run an executable program, or a batch file where: aprogram: a valid OS/2 command, such as the name of an executable program. RETAIN: Retain is used to suppress removal of a TEMP_FILENAME or an EVENT_SEM. RETAIN: YES (or RETAIN: 1) Do NOT reset a semaphore, and do not delete a temporary file RETAIN:NO (or RETAIN: 0) Reset a semaphore, and delete a temporary file The default is RETAIN: NO. --------------------------------- IV. Example of an EVENTS.CFG file ; see below for a sample of a "shutdown GoServe" REXX program, that ; works with this event entry Type: SEMAPHORE \SEM32\SHUTDOWN_1 Action: shutdown ; these next three tell SRE-http to look for a "flag file", and ; if found: ; i) temporarily suspend (refuse further connections) ; ii) do a (possibly time-consuming) "cleanup" ; iii) resume (accept further connections) Type: F e:\goserve\flags\flag.1 Action: SUSPEND Retain: Yes Type: F e:\goserve\flags\flag.1 Action: Call e:\goserve\cleanup.cmd Retain: Yes ; note the use of "RETAIN:" in the two preceeding entries. Type: F e:\goserve\flags\flag.1 Action: resume ; Be sure to end each "line", of a block of interpretable REXX code, ; with a semi-colon Type: Procedure check_time Action: interpret atime=time('n') ; adate=date('n') ; call pmprintf("Today's date is: "||atime||' '||adate) --------------------------------- V. Example of a REXX program to shutdown GoServe In conjunction with the first entry in the sample EVENTS.CFG file, this program can be used to shutdown your server. /* Signal GoServe/SRE-http to shutdown */ /* 1) create a semaphore */ foo=eventsem_create('\SEM32\SHUTDOWN_1') /* 2) Post it */ foo=eventsem_post('\SEM32\SHUTDOWN_1') /* 3) Optional -- post a semaphore to force SRE-http to shutdown immediately. If you do not include this line, then SRE-http may wait "EVENT_CHECK" minutes before checking this shutdown event. */ foo=eventsem_post('\SEM32\SREF_80_EVENT_CHECK') .end of documentation