MFS PROGRAMMING & USAGE

One of the roles played by an MFS is that of monitoring specific functions and disabling them under certain circumstances. An example is that of a security MFS that monitors all reads and writes to a file, and permits only authorized users to execute these functions.

The standard method for disabling a function is for the MFS to set the STATUS argument to false, and to execute a RETURN statement immediately. The MFS should normally not call subsequent filing systems, since these may proceed with the operation (such as creating a file or updating a record), reset the value of STATUS, or set the value of other variables used in detecting the success of an operation.

In many cases, the R/BASIC command that generated the MFS call will fall through its ELSE logic when detecting a status of false. This is the case, for instance, for the R/BASIC READ command. Many TCL commands (MAKEFILE, ATTACH, etc.) will also post a message indicating that the command could not be executed.

The program fragment below illustrates a simple method for disabling the READ.RECORD code:

READ.RECORD:  
GOSUB CHECK.SECURITY  
IF SECURITY.CHECK = PASSED$ THEN  
   GOSUB NEXT.MFS  
END ELSE  
   STATUS = 0  
END  
RETURN  

This method of disabling functions means that a subsequent MFS does not have an opportunity to act upon the code being called. This has implications for the ordering of MFSs. For example, if an audit trail MFS is required to record an attempt to read, write or delete all records – even if these functions are not successful – the audit trail MFS must precede any security MFS that might abort the record operation.

Not all functions translate a status value of false directly into a failure. For example, an R/BASIC SELECT statement does not look at the return value of STATUS. Instead, the SELECT statement examines the value of RECORD to determine whether a select condition is active. The value of RECORD is translated into the value of the system variable @LIST.ACTIVE, which is in turn read by subsequent READNEXT statements. If RECORD (and by extension, @LIST.ACTIVE) is false, a READNEXT statement will fall through its ELSE logic.

Details about non-standard methods of disabling particular calls can be found in the "MFS Operations Reference" section of this book.

Because a call to an MFS is generated indirectly via R/BASIC statements, programmers do not have a facility for passing data directly to an MFS. Unless the MFS is called directly, the programmer has little control over the argument list passed to the MFS.

Programmers must therefore rely on other means of communicating with an MFS. One method is to use global or labelled common areas. The other is to use the contents of arguments (such as the contents of data records) to pass information to the MFS.

Global areas available to an MFS include system @-variables (@USERNAME, @ENVIRON.SET, etc.), user-defined global variables (@USER0-4), and labelled common areas.

A security MFS, for instance, might use the user name and privilege level variables to control access to files. A more sophisticated security system can establish a labelled common area at logon time. The labelled common area might contain lists of files and fields that the user has access to, to be examined by the MFS at every file operation.

The arguments for filing system calls come from the various elements of R/BASIC statements. A programmer can thus pass information or keys to the MFS by simply passing them along with data.

One example is the TCL MAKEFILE command. All parameters following the filename are passed intact to the filing system for its own use. A developer could pass any number of parameters to an MFS by simply adding them onto the ones already being passed. The MFS would examine the parameter string, extract its own parameters, and pass the remaining ones on for further processing.

Programmers can even use R/BASIC READ and WRITE statements to pass information, using the key or record variables. As in the last example, the programmer adds the MFS-specific information into the key or record. The MFS strips the information for its own use, and passes clean data on for further processing.

An example is an encryption MFS that relies on an encryption key. The developer can concatenate the encryption key onto the record key using a specific delimiter, then simply read or write the data. The MFS can strip the encryption key from the record key, and then pass the key on to the filing systems that follow.

Because this requires that the encryption key be passed with the record, it provides a much higher level of security than a single-key encryption MFS. The developer can create windows in which a pre-read and pre- write process tacks a window-specific encryption key onto the record key. This limits access to the data to that window.

While this method is very useful, it also requires caution. As a rule, if an MFS is modifying basic data (records and keys), then the position of the MFS in the BFS list is important. For instance, it will be critical to install the MFS correctly with respect to SI.MFS, so that data is indexed properly – not with control information in it.

Programmers should also consider the multiple ways that data can be accessed, and assure themselves that users cannot access or update files in such a way that the MFS is skipped or is confused about data conversion it must do. For instance, if an MFS has been coded to convert data during reads and writes, the developer must guarantee that it will never be called with data that is not to be converted.

A special call is provided to enable an MFS to perform any special processing that might be required to initialize itself. This is the INSTALL call.

The first time an MFS is called for the current session, the Advanced Revelation system calls the MFS with an INSTALL code. The MFS can perform any action that it requires in order to run properly, including initializing files, establishing buffers or caches, checking security, etc.

Once this logic has been executed, the MFS should execute a RETURN with STATUS set to true. The MFS should not attempt to call subsequent MFSs or the BFS directly, since the BFS argument will not contain the names of any of these. Unlike most MFS calls, INSTALL is not called by Advanced Revelation in anticipation of eventually passing the call to the BFS. The INSTALL call is a direct call to that MFS only. If a call is attempted to the next MFS, a load error will occur.

All MFSs should thus execute the following logic upon encountering an MFS call:

INSTALL:  
(MFS-specific initialization logic here)  
STATUS = 1  
RETURN  

Once the MFS has successfully returned from an INSTALL call, INSTALL will not be called again. The name of the MFS will be stored in a special system variable, and will remain there for the duration of the session.

There is no effective way to de-install the MFS from the system. Once the MFS has been installed, the system will assume that the MFS will be available until the user logs out of Advanced Revelation. This is true even if all files for which the MFS is installed are detached.

Because of this, an MFS must remain available at all times. The system occasionally generates direct calls to each MFS it believes is available. The most common of these is the FLUSH call. If the system makes such a call, and the MFS object code is not available, a load error will occur.

In many cases the only recovery is to reset the system. In some cases, however, it may be possible to use the debugger EXECUTE command to reattach the file containing the MFS object code.

A call that MFS programmers will find executed often is FLUSH. This call is used by Advanced Revelation to alert all filing systems that they should flush any cached information to disk. FLUSH is called when the system resets (such as upon executing END from the debugger), when a file or volume is detached, or when logging off. Advanced Revelation's indexing system also calls FLUSH.

The FLUSH call is a direct call to each filing system currently installed (see INSTALL, above), rather than a call to a specific file. An MFS should therefore not attempt to pass a FLUSH call through to the next filing system. The BFS argument that normally contains a full list of filing systems will contain only the name of the MFS being called. Attempts to pass the call through to the next BFS will result in load errors.

A MFS does not typically need to include logic that causes flushing. Of course, an MFS can use the FLUSH call for its own purposes, including any type of system cleanup required for an MFS.

Even if the MFS does not use the FLUSH call, it should include this logic:

 
FLUSH:  
STATUS = 1  
RETURN  

Status is always set to true, and that there is no call to the next filing system.

Note: an MFS will be called with a FLUSH command if it has been installed during the current session, even if no files using that MFS are currently attached. It is therefore important that an MFS remain available at all times during the session in which it has been installed. Do not detach a file containing an MFS currently installed, and do not detach the VOC file in which an MFS has been cataloged.