An improvement suggestion is made to the current version (v7.8.20-1) of the Standard Library Reference manual to provide additional details about the functioning of the start and finish transaction frames for the maintenance of superfiles in pages 31 and 39, respectively.
The suggested verbiage for the description of the StartSuperFileTransaction function on page 31, is as follows:
"The StartSuperFileTransaction function begins a transaction frame for superfile maintenance. The transaction frame is terminated by calling the FinishSuperFileTransaction function. Within the transaction frame, multiple superfiles may be maintained by using SuperFile Maintenance functions to add, remove, clear, swap, and replace sub-files.
You must use the SEQUENTIAL action to ensure ordered execution of the function calls within the transaction frame. This way, the SuperFile Maintenance functions are called in the order that they are listed between the transaction frame´s start and finish functions, but they are only committed once (i.e., actually executed) at the finish transaction function. The first SuperFile Maintenance function called within the transaction frame initiates a “read” lock on the superfile until the commit. At commit, the superfile is “write” locked for the transaction to actually execute, and all locks are released at the end of the commit. It is important to note that any calls to functions other than SuperFile Maintenance functions within the transaction frame are not part of the transaction frame (even though they are executed in the order written). The “read” lock is only generated when the first SuperFile Maintenance function is called. While the superfile is “read” locked, no concurrent “write” locks can modify the superfile. During the timeframe of the “write” lock at commit (usually small time window), no concurrent “read” locks are allowed. Therefore, the SuperFile Maintenance functions must be called within a transaction frame to avoid the possibility of another process may try to modify the superfile during sub-file maintenance. As a result, maintenance work can be accomplished without causing problems with any query that might use the SuperFile.
The FinishSuperFileTransaction function does an automatic rollback of the transaction if any error or failure occurs during the transaction frame. If no error occurs, then the commit or rollback of the transaction is controlled by the rollback parameter to the FinishSuperFileTransaction function."
The suggested verbiage for the description of the FinishSuperFileTransaction function on page 39, is as follows:
"The FinishSuperFileTransaction function terminates a superfile maintenance transaction frame. If the rollback flag is FALSE, the transaction is committed atomically and the transaction frame closes. Otherwise, the transaction is rolled back and the transaction frame closes. At commit, the superfile is “write” locked for the transaction to actually execute, and all locks are released when the transaction frame closes. During the timeframe of the “write” lock at commit (usually small time window), no concurrent “read” locks are allowed."