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 hook.def):
Field |
Type |
Meaning |
|---|---|---|
event |
b,4 |
event code (see HPE_xxxx flags) |
flags |
b,4 |
event processing flags (see HFF_xxx) |
fileid |
b,4 |
unique file id # |
recno |
f,8 |
rec # |
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 |
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 (immediately prior to being written). Warning: the "previous contents" will be null if the previously read record number is not the same one being written. (A better way to handle that situation may come later.)
Comments
A sample hook (FSHOOK1) and sample program (FHOOKTST1) can be found in [908,50] of the EXLIB.
WARNING/REMINDER: The file hook mechanism was introduced in 5.1.1174, and thus may be subject to further fixes and refinements over the next few program edits.
