A-Shell Consolidated Reference

Updated September 2017

xcall MIAMEX, MX_FILEHOOK, opcode, status, file {,fid, handler, events, flags, enabled}

MX_FILEHOOK (MIAMEX 178) allows you to establish file "hooks" on specific files and file events. The "hook" is a means by which you can insert a call to a "handler" (sometimes referred to as a "plug-in") into the midst of what would otherwise be an entirely internal operation, allowing you to monitor, filter, or otherwise customize the operation. Typical uses for file hooks are:  

Parameters

opcode (Num)  [in]

may be one of the following (defined in ashinc:hook.def):

 

status (Signed Num)  [out]

returns status code:

 

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. Note that in the case of ISAM and ISAM-A files, you must specify the extension, typically IDA or DAT.

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 (HOOKOP_ADD), it must specify the handler for the hook, using one of the following syntax variations:

SBX:sbxnam

LOGFIL:fspec

 

In the case of the SBX:sbxnam handler, A-Shell will XCALL the specified SBX subroutine (sbxnam) to process the hook, allowing you to add custom logic into the file operation in real time. Note that sbxnam is limited to a maximum of six characters, e.g. SBX:AROPEN. In the case of the LOGFIL:fspec handler, A-Shell uses its own built-in logic to output information about the event to the specified file, allowing you to process the log file later. Each type of hook is described in greater detail in the sections that follow.

For opcode 6 (HOOKOP_APPEVENT), the handler parameter may be used to pass an arbitrary string to the handler previously set up by opcode 2. Typically this may be used to send a contextual message to the handler, such as "starting check run" or "posting run complete".

events (B4)  [in]

a bit-field of events to hook, from the following (defined in ashinc:hook.def):

 

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 ashinc:hook.def):

 

Note that for the SBX handlers, most of the flags affecting the data that is included in the information passed to handler are ignored. The packet is a fixed size and there is nothing to be gained by blanking out certain fields. The flags which do matter are: HFF_DATA and HFF_DATA_WAS, HFF_DATA_CHG_ONLY, and HFF_AUTO_DEL.

enabled  (Num)  [out]

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

 

Comments

Hook definitions are not directly affected by file open and close operations. Nor are they affected by termination of the program unless the HFF_AUTO_DEL flag is specified when the hook is established. They are automatically removed by termination of the A-Shell session. So you can add/delete all your file hooks in a common application startup/shutdown program, without making any modifications to the individual programs which operate on the files.

MX_FILEHOOK works with random, ISAM, and ISAM-A files. In the case of ISAM and ISAM-A files, only the data file is hooked.

Example

Use the following pattern to establish a file hook...

    ++include'once ashinc:ashell.def

    ++include'once ashinc:hook.def

 

    define FID_CUST    = 1001            ! file ID for customer file

 

map1 hook'vars

    map2 hook'status,f

    map2 hook'file$,s,40

    map2 hook'fid,b,4

    map2 hook'handler$,s,16

    map2 hook'events,b,4

    map2 hook'flags,b,4

 

hook'file$    = "DSK2:CUST.DAT[100,50]"

hook'fid      = FID_CUST

hook'handler$ = "SBX:MYHOOK"

hook'events   = HFE_POST_OPEN or HFE_POST_WRITE or HFE_POST_WRITEL or HFE_POST_CLOSE or HFE_PRE_ALLOC

hook'flags    = HFF_PROG or HFF_SBX or HFF_RECNO or HFF_TIME or HFF_DATE  &

                or HFF_USER or HFF_DATA or HFF_DATA_WAS 

 

xcall MIAMEX, MX_FILEHOOK, HOOKOP_ADD, hook'status, hook'file$, hook'fid, hook'handler$, hook'events, hook'flags

if hook'status < 0 then ? "Error setting hook: ";hook'status

 

After the above code is executed the hook handler (MYHOOK.SBX) will be called after every open, write, writel and close operation on the file DSK2:CUST.DAT[100,50], and also every allocate operation on the file. See the following topic Hook SBX Specification.

The above example could be changed to use the LOGFIL: handler instead, by changing the hook'handler$ assignment to something like:

hook'handler$ = "LOGFIL:APPLOG:FILEIO.LOG

or

hook'handler$ = "LOGFIL:dsk0:audit.log[1,2]

See the following topics, File-Based File Hook Handler and MX_FILEHOOK Support for ISAM-A, for more details.

 

History

2018 July, A-Shell 6.5.1642:  Added handler LOGFIL: and File-Based File Hook Handler to A-Shell

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 EXLIB:[908,50] have been updated to illustrate both hooks.