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 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]<version> |
start event prefix followed by version, currently 1 |
[&h82]<timestamp> |
(optional) timestamp, ST_HOOK_TIMESTAMP |
[&h83]<env> |
uncompressed hook env, ST_HOOK_ENV |
[&h84]<squeezed env> |
'squeezed' version of hook env |
[&h85]<prerec> |
raw prerec (rec deleted or prior to update) |
[&h86]<squeezed prerec> |
'squeezed' version of prerec |
[&h87]<rec> |
raw rec (updated record) |
[&h88]<squeezed rec> |
'squeezed' version of rec |
[&h8A]<app msg> |
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] 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] 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
