Added January 2010
The file hook mechanism allows you to establish file "hooks" on specific files and file events. The "hook" is an SBX which is called automatically by A-Shell when the specified event occurs on the file. The SBX may then output auditing information, check for anomalies, enforce rules, export data, essentially whatever it likes.
To establish a hook on a file:
++include ashinc:ashell.def
++include ashinc:hook.def
xcall miamex, MX_FILEHOOK, opcode, status, file {,fid, handler, events, flags, enabled}
Note that MX_FILEHOOK operations work with old ISAM files, at least for the standard file operations (OPEN, READ, WRITE, CLOSE) on the IDA file. There is no point in hooking the IDX file, as the ISAM statements themselves have no hook processing.
See the following topic Hook SBX Specification.
Parameters
opcode (Num) [in]
may be one of the following (defined in hook.def):
|
Symbol |
Value |
Meaning |
|
HOOKOP_DISABLE |
0 |
disable one (or all) hooks |
|
HOOKUP_ENABLE |
1 |
re-enable one (or all) hooks |
|
HOOKUP_ADD |
2 |
add a new hook |
|
HOOKOP_DEL |
3 |
delete a hook |
|
HOOKOP_APPEVENT |
6 |
call the hook to process an app-defined event |
|
HOOKOP_QRY |
7 |
query a file hook by its fileid or filespec. If found, the status will be >= 0 and all of the remaining fields will be returned. See SOSLIB sample/utility program QRYHOOKS.BP[908,50] for example of querying the file hook table. |
status (Signed Num) [out]
returns status code:
|
Value |
Meaning |
|
>=0 |
success |
|
-1 |
unable to allocate memory for hook table |
|
-2 |
illegal fspec (must be AMOS-style) |
|
-3 |
invalid handler syntax |
|
-4 |
fspec not found (opcode 0,1,2,6) |
|
-5 |
fid not found (opcode 0,1,2,6) |
|
-6 |
opcode not yet implemented |
|
-7 |
illegal opcode |
file (String) [in]
is the specification of the file whose operations are to be hooked. (Only AMOS-compatible filespecs are currently suported.) Note that with opcode 0, 1 and 3, file may be "*" to perform the operation on all the hooks in the hook table.
fid (Num) [in]
a unique integer identifier for the file, which will be used in any output files to reference the file (more compact than outputting the file spec each time.)
handler (String) [in]
depends on the OP. For opcode 2 (add), it must specify the handler for the hook, using the following syntax:
SBX:xxxxxx
where xxxxxx is the name of an SBX file, which will be called to process the hook. (see "HOOK SBX SPECIFICATION" below for further details. Note that additional handler types (and corresponding syntax), such as a text file, FIFO, or TCP connection, may be defined later.
For opcode 6 (HOOKOP_APPEVENT), the handler parameter may be used to pass an arbitrary string to the hook routine. Typically this may be used to include a message in the hook log file, such as "posting run complete".
enable (Num) [out]
returns 0 or 1 to indicate if the hook is disabled or enabled.
events (B4) [in]
a bit-field of events to hook, from the following (defined in hook.def):
|
Symbol |
Value |
Meaning |
|
HFE_PRE_OPEN |
&h00000001 |
prior to open |
|
HFE_POST_OPEN |
&h00000002 |
after open |
|
HFE_PRE_CLOSE |
&h00000004 |
prior to close |
|
HFE_POST_CLOSE |
&h00000008 |
after close |
|
HFE_PRE_READ |
&h00000010 |
prior to read or get (any) |
|
HFE_POST_READ |
&h00000020 |
after read or get (any) |
|
HFE_PRE_READL |
&h00000040 |
prior to readl or getl |
|
HFE_POST_READL |
&h00000080 |
after readl or getl |
|
HFE_PRE_WRITE |
&h00000100 |
prior to write (or update'record) |
|
HFE_POST_WRITE |
&h00000200 |
after write (or update'record) |
|
HFE_PRE_WRITEL |
&h00000400 |
prior to writel (or create'record) |
|
HFE_POST_WRITEL |
&h00000800 |
after writel (or create'record) |
|
HFE_PRE_ALLOC |
&h00002000 |
prior to allocate |
|
HFE_POST_ALLOC |
&h00004000 |
after allocate |
|
HFE_PRE_KILL |
&h00008000 |
prior to kill |
|
HFE_POST_KILL |
&h00010000 |
after kill |
|
HFE_PRE_SORT |
&h00020000 |
prior to allocate |
|
HFE_POST_SORT |
&h00040000 |
after allocate |
|
HFE_APP_EVENT1 |
&h10000000 |
custom application event |
flags (B4) [in]
a bit-field of flags which are passed to the hook routine (as a clue to how the hook should operate), and/or which are used by A-Shell to modify the operation of the hook (from hook.def):
|
Symbol |
Value |
Meaning |
|
HFF_PROG |
&h00000001 |
include program name |
|
HFF_SBX |
&h00000002 |
include sbx name |
|
HFF_DATA |
&h00000004 |
include copy of data just written (POST_WRITE only) |
|
HFF_DATA_WAS |
&h00000008 |
include copy of data as previously read or written, for comparison with data now being written (POST_WRITE only) |
|
HFF_RECNO |
&h00000010 |
include recno |
|
HFF_TIME |
&h00000020 |
include time |
|
HFF_DATE |
&h00000040 |
include date |
|
HFF_USER |
&h00000080 |
include user name |
|
HFF_PID |
&h00000100 |
include process id |
|
HFF_AUTO_DEL |
&h00001000 |
auto delete hook on prog exit |
|
HFF_DATA_WAS_NA |
&h00010000 |
there is no "was" data available to pass to the hook routine in response to the HFF_DATA_WAS flag |
|
HFF_DATA_CHG_ONLY |
&h00020000 |
may be used in conjunction with HFE_POST_WRITE to suppress calling the hook function after the write if the record data hasn't changed. |
enabled [out]
returns zero or one to indicate if the hook is disabled or enabled.
History
2011 June, A-Shell 5.1.1221
Added flag HFF_DATA_CHG_ONLY to suppress calling the hook function after the write if the record data hasn't changed.
2010 December, A-Shell 5.1.1197
File hook refinement: When there is no "was" data available to pass to the hook routine (in response to the HFF_DATA_WAS flag), A-Shell now sets a new flag, HFF_DATA_WAS_NA (&h00010000) in the flags field in the hook environment structure passed to the hook routine. This allows the hook routine to distinguish between an empty prior record and unknown prior record contents. (The prior contents of the record can only be supplied to the hook routine if the last record # read is the same record # being written.)
ASHINC:HOOK.DEF has been updated with the new flag, and the sample hook routine FHOOK1.BP (SBX) has been updated to show testing the flag.
2010 January, A-Shell 5.1.1174 – Added routine to A-Shell
