MIAMEX 178: Establish File Hooks

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 EXLIB sample/utility program QRYHOOKS.BP[908,50] for example of querying the file hook table.
Definition File: HOOK.DEF

 

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 supported. 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 opcode. 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 the following topic, Hook SBX Specification, 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".

events  (B,4)  [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 sort
HFE_POST_SORT	&h00040000	after sort
HFE_ISAM_ADD	&h00080000	after ISAM 5 (add); see History
HFE_ISAM_DEL	&h00100000	after ISAM 6 (delete); see History
HFE_APP_EVENT1	&h10000000	custom application event
Definition File: HOOK.DEF

 

flags  (B,4)  [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.
Definition File: HOOK.DEF

 

enabled  (Num)  [out]

returns zero or one to indicate if the hook is disabled or enabled.

History

2015 February, A-Shell 5.1.1402:  Added events HFE_ISAM_ADD and HFE_ISAM_DEL. Note that unlike most of the other file hooks, these don't come in PRE- and POST-flavors. For the ADD hook, the record data supplied to the hook routine (rec parameter) will contain the key rather than the record data. Since ISAM adds are followed by a WRITE statement, you can hook that to get the contents of the record itself. For the DEL hook, the record data of the record being deleted is supplied to the hook routine in the pre'rec parameter. The rec parameter should be ignored. The sample hook program FHOOKTST3.BP and hook subroutine FHOOK1.SBX in [908,50] of the EXLIB have been updated to illustrate both hooks.

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:  Routine added to A-Shell