# File-Based File Hook Handler _Added July 2018_ Beginning with A-Shell 6.5.1642 of August 2018, a file-based file hook handler option may be specified by setting the MX\_FILEHOOK handler parameter to LOGFIL:fspec where fspec is the AMOS- or native-style file spec for the hook log file. Intead of calling an SBX for each hooked event, it writes an event record to the log file. The potential advantages of the LOGFIL: handler over the original SBX: handler are: • It separates and optimizes the part of the operation that is time sensitive—the event handling itself—from the part which isn't—the final or back-end processing of the event records, whether for auditing, replication to remote databases, or simply archival. The time sensitive part event handling part is considerably faster than the SBX event handlers, creating less drag on the application. • It is easier to implement, since the handler itself requires no programming or debugging. You still need to write some code to process the log file created by the handler, but there is typically little time sensitivity for that. • It allows for multiple hook processes per file without any additional impact on the application's real-time performance, since the logs can be processed multiple times by multiple processes any time later. • The log files can be processed on remote machines, either by writing the log files to a network-mounted directory, or transferring them to another machine for final processing. Three new flags have been added to the [ASHINC:HOOK.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/hook.def) to support new options associated with the new handler: | **Symbol** | **Value** | **Description** | |------|------|------| | HFF\_TIMESTAMP | \&h00000060 | Include timestamp in log for each event | | HFF\_SQZ\_ENV | \&h00080000 | 'squeeze' env rec (LOGFIL: hooklogs) | | HFF\_SQZ\_DATA | \&h00100000 | 'squeeze' data recs (LOGFIL: hooklogs) | The timestamp uses the following structure (HOOK.DEF) : defstruct ST\_HOOK\_TIMESTAMP map2 date,b,4 \! separated date format map2 msecs,b,4 \! milliseconds since midnight endstruct Each event record in the hook log file consists of the following fields, most of which are equivalent to the parameters passed to the SBX version of the hook, and each of which is preceded by a prefix byte—represented below as \[hex value\]—to help ensure correct/synchronized/adaptable interpretation of the log. Note that some of the fields come in raw or 'squeezed' versions, depending on HFF\_xxx flags passed to MX\_FILEHOOK. This is described in further detail below. | **Symbol** | **Description** | |------|------| | \[\&h80\] | start event prefix followed by version, currently 1 | | \[\&h82\] | (optional) timestamp, ST\_HOOK\_TIMESTAMP | | \[\&h83\] | uncompressed hook env, ST\_HOOK\_ENV | | \[\&h84\] | 'squeezed' version of hook env | | \[\&h85\] | raw prerec (rec deleted or prior to update) | | \[\&h86\] | 'squeezed' version of prerec | | \[\&h87\] | raw rec (updated record) | | \[\&h88\] | 'squeezed' version of rec | | \[\&h8A\] | msg from app with HOOKOP\_APPEVENT; max 256 chars | | \[\&h8F\] | event record terminator | • The timestamp field is included if the HFF\_TIMESTAMP—HFF\_TIME or HFF\_DATE—flag is set in the MX\_FILEHOOK call. • The env (environment) field—ST\_HOOK\_ENV, identical to the environment passed to the SBX handler—is always included; either in raw format (default) or, in 'squeezed' format if the HFF\_SQZ\_ENV flag was passed to MX\_FILEHOOK. • The prerec and rec fields are included under the same conditions that they would be passed to the SBX form of the hook. By default they are in raw (binary) format but may be 'squeezed' if the HFF\_SQZ\_DATA flag was passed to MX\_FILEHOOK when the hook was established. • The app msg field is only present if MX\_FILEHOOK is called to send an app-defined message to the hook. • The 'Squeezed' format is an A-Shell-specific lightweight data compression scheme designed explicitly for typical data records. These are typically too small for other compression algorithms, 32 bytes to maybe 4K, and because the most common data storage formats used in fixed length records are likely to have consecutive runs of nulls, spaces, zeroes, and/or brackets ("\]"). The 'squeezed' format reduces all such consecutive runs of 3-63 bytes to 2 bytes. The penalty is that individual bytes of value \&hDD (221) are also encoded into 2 bytes. So the worst case scenario would be a record where every other byte is \&hDD, which would be 50% larger in the 'squeezed' format than the raw. But that is an exceedingly minute likelihood; in the vast majority of cases, the 'squeeze' will result in a significant reduction in the log file size. The module [FNFHOOKLOG.BSI in SOSLIB\[907,10\]](https://bitbucket.org/microsabio/soslib/src/master/907010/fnfhooklog.bsi) provides a convenient function, Fn'Hooklog'Read'Event(), which is able to split out an event record from the log, whether squeezed or not, into the various fields. The test/demo program [FHOOKTST4.BP in EXLIB:\[908,50\]](https://bitbucket.org/microsabio/exlib/src/master/908050/fhooktst4.bp) illustrates both initializing a LOGFIL: hook handler but also reading from the log created, producing a CSV file representation. **History** 2018 July, A-Shell 6.5.1642: Function added to A-Shell