# Hook SBX Specification

> [HTML Version](hooksbxspecification.htm)

_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](num.htm.md))  \[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](https://bitbucket.org/microsabio/soslib/src/master/907016/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](string.htm.md) 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\]](https://bitbucket.org/microsabio/exlib/src/master/908050/).

**Comments**

2016 November, A-Shell 6.3.1538:  Add _envelope_ fields channel, location and line number. 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](https://bitbucket.org/microsabio/soslib/src/master/907016/hook.def) for the updated structure and related symbol defintions.