Hook SBX Specification
Updated November 2016
The SBX you specify to handle the hook will be called automatically by A-Shell for the specified events, as follows:
xcall <NAME>, sts, envelope, rec, pre'rec
Parameters
sts (Num) [in]
returns 0 for ok. Any odd value returned from a HFE_PRE_xxx event will cause A-Shell to skip the event. This allows you to completely replace the file operation originally programmed, with one of your own.
envelope (ST_HOOK_ENV structure) [in]
a structure containing the following information (defined in ashinc:hook.def):
Field |
Type |
Meaning |
|---|---|---|
event |
b,4 |
event code (see HFE_xxxx flags) |
flags |
b,4 |
event processing flags (see HFF_xxx) |
fileid |
b,4 |
unique file id # |
recno |
f,8 |
rec #. Note that this will always be zero-based, regardless of the actual FILEBASE setting in either the hook SBX or in the main program. |
pid |
b,4 |
process id |
recsiz |
b,4 |
record size |
mode |
b,4 |
mode (depends on event) |
prog |
s,16 |
program name |
sbx |
s,16 |
sbx name (if appl) |
user |
s,24 |
user name |
chan |
b,4 |
actual file channel; might not match fileid |
location |
b,4 |
location counter |
lineno |
b,2 |
last line number |
rec (String or x) [in]
contains data relative to the event. For the HFE_POST_READx and HFE_xxxx_WRITEx events, it will contain the record data which was just read or which is to be (or was just) written. For the OPEN, ALLOC and KILL events, it will contain the filespec (in native format). For the APPEVENT event, it will contain the contents of the HANDLER$ parameter passed to the MX_FILEHOOK call. For other events, it may be undefined.
pre'rec (X) [in]
used only with the HFE_POST_WRITE event, when the HFF_DATA_WAS flag is set, in which case it will contain the previous contents of the record (at the time of the last read or write operation on the file). Warning: this mechanism only works when no other records in the same file were accessed since the last read or write of this record. If other accesses have occurred, the contents of pre'rec will be empty.
Comments
The sample hook FHOOK1 and sample program FHOOKTST1 can be found in EXLIB:[908,50].
Comments
2016 November, A-Shell 6.3.1538: Add envelope fields chan, location and lineno. These are mostly motivated by the desired to use the hook mechanism for application forensics that for more traditional purposes (export, data audit), i.e. they allow the hook return to more information context in which the file operation occurred. The new fields do not break compatibility with existing hook routines, nor do hook routines using the expanded structure lose their backwards compatibility; the new fields just won't be available. See ASHINC:HOOK.DEF for the updated structure and related symbol defintions.
