{}
{   A file_access_procedure (fap) is a procedure which intervenes in the
{ calling sequence sequence between a task and the access method.  When a}
{ task issues an access method request which is keyed by a file_identifier,}
{ control passes directly to the fap rather than the access method.}
{}
{ Possible reasons for using faps include:
{}
{       .encryption / decryption
{       .modeling the task's i/o behavior
{       .file data conversion
{       .file data compression
{       .logging of change/access to a file
{       .stubbing-off a program's i/o during program debugging
{}
{   When a file is created a fap may be specified by the SET_FILE_ATTRIBUTES}
{ command, the amp$file request or the amp$open request. The}
{ file_access_procedure is specified as a name and that name is preserved}
{ with the file.}
{   The fap is loaded each time the file with which it is associated is}
{ opened.  The association of a fap with a file does not bestow additional}
{ privilege upon the fap. The privilege of the fap is determined by the}
{ privilege of the file from which the fap is loaded, qualified by the ring}
{ of the caller of open.  The fap cannot access the file unless the fap has}
{ the neccessary privilege, but it may simulate file access.}
{ Failure to successfully load the fap will result in abnormal status and}
{ the termination of the amp$open request.}
{   A fap must be coded to accept any and all access method requests which}
{ pass control to a fap. The call_block formal parameter description}
{ describes which access method requests are applicable. With few}
{ exceptions, this list consists of all access method requests which have}
{ file_identifier as a formal parameter. Whenever such a request is issued}
{ by a task, the request is immediately diverted to the fap before}
{ any action is taken by the access method.}
{   The fap may choose to process the request itself, i.e. emulate the}
{ access method, or it may choose to pass the request to the access method.}
{   If the fap chooses to emulate the access method, the fap is responsible}
{ for executing the request in a manner which is functionally compatible}
{ with the access method it replaced. This responsibility extends to}
{ initializing the task's STATUS variable and other actual}
{ parameters, where applicable, in addition to transferring data.}
{   If the fap chooses to pass the OPEN operation to the access method}
{ then it may do more than merely emulate requests. The fap may issue}
{ multiple requests upon the access method to implement the task's}
{ request. However, by choosing to pass the OPEN operation, the fap must}
{ pass the CLOSE operation as well. Any file which is not explicitly closed}
{ by the task will be closed at task termination. The fap will be}
{ given control at that time via the CLOSE operation. As in the explicit}
{ CLOSE, the fap must pass CLOSE to the access method.}
{   If the fap chooses to pass the task's request to the access}
{ method, it does so with the amp$access_method request. This interface may}
{ also be used to issue access method requests other than those issued by}
{ the task. The amp$access_method interface is only to be used to}
{ access the instance of open defined by the file_identifier, which}
{ is an actual parameter to the fap. A fap may access other files using the}
{ 'AMP$' interfaces (provided that it is not the fap for any of them).}
{ A fap which issues 'AMP$' requests to a file for which it is defined as}
{ the fap, will recursively call itself. This will be true for all requests}
{ defined by the amt$fap_operation type declaration.}
{   The file_access_procedure preserved with a file is always the first}
{ process to gain control from whichever 'AMP$' interface was executed}
{ by the task. There may exist other faps defined by the system. These}
{ system faps would be given control if the file_access_procedure were}
{ to pass a request using amp$access_method. To coordinate the order in}
{ which faps are given control, a layer_number is passed to the fap as}
{ a parameter; the layer_number must not be changed by the fap since it is}
{ the key by which the fap is known within the ordering (layering) of faps.}
{ The layer_number given to the fap is the one which is used as an input}
{ to interfaces which support the fap mechanism.}
{   Each layer of fap has the ability and responsibility for interpreting}
{ and providing STATUS for the layers above it.}
{   If the fap detects an exception condition during the OPEN operation,}
{ it must return an initialized status variable rather than trying to}
{ CLOSE the file itself. The amp$open interface will detect the abnormal}
{ status, call the fap with a CLOSE operation, and return the abnormal}
{ status to the task. This allows each layer of fap to see the close.}
{   The following is a description of the formal interface to a fap.}
{ The fap writer should use the amt$fap_pointer type declaration as a guide}
{ to producing the [XDCL] procedure declaration for the fap. The fap}
{ interface must be compatible with the CYBIL language's calling sequence}
{ and data mapping.}
{}
{       FILE_ACCESS_PROCEDURE_NAME (FILE_IDENTIFIER, CALL_BLOCK,
{         LAYER_NUMBER, STATUS)
{}
{ FILE_IDENTIFIER: (input) This parameter specifies the file access identifier}
{       which was quoted on the task's call to the access method.}
{}
{ CALL_BLOCK: (input) This parameter specifies the identity and the substance}
{       of the operation which the fap is requested to perform.}
{}
{ LAYER_NUMBER: (input) This parameter specifies the identity of the fap.}
{}
{ STATUS: (output) This parameter specifies the request status.}
{}
