MFS PROGRAMMING & USAGE

An MFS may require record locking as part of its own processing. This will be the case, for instance, if an MFS such as an audit trail MFS must update files. As with any program, if executing in a network environment, the MFS should preserve file integrity by locking all records that are to be updated.

If an MFS must lock records, it should never do so with direct calls to the filing system. Instead, the MFS should execute R/BASIC LOCK calls. Moreover, when executing the R/BASIC LOCK calls, the MFS should always first fetch a proper file handle using an R/BASIC OPEN statement.

(Note that this is in contrast to the method used to access data in the file – see the topic "Access to a File from Within an MFS" earlier in this chapter. Access to the same file should not be done via R/BASIC statements, whereas locking always must be done via R/BASIC OPEN and LOCK.)

By executing an R/BASIC LOCK statement, the local lock table will be updated properly. A direct call to the filing system will not pass through the R/BASIC interpreter, and the local lock table will not be aware of locks made in this way; coordination with locally-held semaphores will not be possible.

In order to pass the proper file handle to the LOCK statement, the MFS should first fetch the handle using an R/BASIC OPEN statement. Though it might seem possible to use the HANDLE argument if locking files in the current file, the HANDLE argument does not contain the same handle information as returned by an R/BASIC OPEN statement. Since application programs use the full R/BASIC OPEN file handle when locking, an MFS should do so as well in order to guarantee coordination with these higher-level processes.

Lock calls pass the lock type in the FMC argument. This type determine whether a lock is exclusive, shared, or coordinated. It also indicates whether the lock call concerns a file, record, group or other entity.

If the lock is a coordinated lock, two lock calls will be made. The first locks the file, and the second (if the first was successful) locks the record.

The UNLOCK.ALL call functions differently than other lock calls. When an R/BASIC UNLOCK ALL statement is executed, the system does not pass individual lock calls to each open file.

Instead, the system reviews the list of installed filing systems and makes a single UNLOCK.ALL call to each filing system. Because this call is directed to the filing system specifically, an MFS receiving an UNLOCK.ALL call does not need to pass the call along to subsequent filing systems. If a call is attempted to the next MFS, a load error will occur.

The system will call all MFSs that have been installed during the current session, even if no files using that MFS are currently attached.

The MFS should simply perform any tasks required to clear all pending locks for that filing system. When this task is complete, the MFS should return with status set to true.

Additional lock calls exist in the system that are not available to MFS programmers. These are calls that the system uses to initialize and reset itself; as a result, these calls are passed only via direct calls at system initialization and reset time.

System lock calls are:

LOCK.SEMAPHORE    
UNLOCK.SEMAPHORE    
SET.USER.SEMAPHORE    

An MFS will never receive these calls, and should therefore simply execute a RETURN for the CODE values of 23, 24, and 25.

A series of MFS calls – examples include CREATE.MEDIA, OPEN.MEDIA, and WRITE.MEDIA – provide MFS programmers with access to media-related file functions. Media calls are defined as those that access the media map for a volume when executing.

The media map is the "directory" that maintains the relationship between Advanced Revelation file names and their actual physical locations (for example, their DOS file names). There is a media map for each subdirectory or drive that contains an Advanced Revelation volume.

Each BFS maintains its own media maps. As a result, it is possible to have more than one media map on a DOS subdirectory. If more than one filing system (BFS) is storing files on a subdirectory, there will be more than one media map. For example, if both Linear Hash (RTP57) and ROS (RTP51) are storing files on a subdirectory, each will have its own media map on that subdirectory. Neither filing system will "know" about the other's files; by extension, neither will be able to access data from the other's files.

In addition to the basic function of mapping Advanced Revelation files to their actual location, filing systems can use media maps for a variety of additional purposes. For example, most filing systems use media maps to maintain information about what MFSs are installed for a file (see the topic "Manual MFS Installation" in the chapter "Installing an MFS" earlier in this book.) However, this is a function of the BFS itself, and restrictions may apply for individual filing systems.

The structure of a media map varies depending on the BFS that maintains it. Most BFSs maintain the media map as a file in their own filing structure. For example, Linear Hash (RTP57) maintains media maps as Linear Hash files, ROS (RTP51) as a ROS file (this is reflected in the DOS name of the media map – REVMEDIA.LK for RTP57, REVMEDIA.000 for ROS).

Some BFSs use a media map structure that is not their default filing structure. The Revelation G BFS (RTP59) uses a media map structure that is not a ROS or LINK file. Another example is provided by Environmental Bonds. Although these BFSs may access data in ASCII, dBASE, or other filing structures, they may at the same time maintain Linear Hash (or other) media map structures.

From the R/BASIC or TCL level, a media map is accessible via the logical file name REVMEDIA. This name is used for all media maps, regardless of volume or filing structure.

To access the media map, a user attaches the logical file name REVMEDIA for the volume being accessed. For example, to attach the media map for the default (REVBOOT) volume, a user executes this command:

ATTACH REVBOOT REVMEDIA    

Note: for security reasons, this command will be successful in the SYSPROG account only.

From this point, the media map can be accessed using any file or record- oriented command. From TCL, this includes the commands LIST, DELETERECORD, and EDIT. From R/BASIC, it includes the commands READ, WRITE, and DELETE.

The media map must be updated anytime a file is created, recreated, renamed, deleted, or moved. In addition, a media map may need to be updated for such functions as MFS installation.

In order to access the media map, Advanced Revelation generates special media access calls. There are calls to initialize, open, read, and write to the media map.

Because the media map is much like a file, access to the media map is much like file access. As with file access, much activity in the media map requires an internal media handle.

The media handle is created by the OPEN.MEDIA call. If successful, this call returns a handle that is used in subsequent media access calls such as READ.MEDIA and WRITE.MEDIA. As with the file handle created by OPEN.FILE, the media handle is stored by the system. The handle returned by OPEN.MEDIA is kept in the VOLUMES file as field five.

If installed only on a file, an MFS will not be able to trap most calls that update the media map. However, if the MFS is installed on a volume as a whole, the MFS will be called for almost all filing system functions, including those that initialize and update the media map.

If able to trap media calls, the MFS can be used for such functions as volume security. For example, a volume-based MFS can prevent users from creating or deleting files without proper access rights. The calls can be disabled by setting the status argument to false and returning without calling the next filing system.

Calls that are available only if the MFS is installed on a volume are:

CREATE.MEDIA    
OPEN.MEDIA    
READ.MEDIA    
WRITE.MEDIA    
CREATE.FILE    

For these calls, information passed in the HANDLE argument is the handle of the media map. This handle is used in virtually the same manner as a file handle.

The OPEN.MEDIA and CREATE.MEDIA calls use the NAME argument to pass a filing system qualifier. The actual definition of this argument is BFS-specific, and can vary from BFS to BFS. For all Advanced Revelation BFSs in Version 1.1, the filing system qualifier is used to pass information about DOS file locations to the BFS. This corresponds to the path name passed as the physical volume name in commands such as MAKEFILE, or to attribute three of a logical volume pointer in the VOC file.