The previous record locking routines lock existing records that your program
is reading or updating. The last set of record locking routines is called when
inserting new records into an RMSfile.
When a record is inserted into a hashed RMSfile, the new record is put into an unused slot in the RMS data file. When a record is inserted into a sequential or indexed RMSfile, it is either added to the end of the file or in stored in the most recently deleted record. It is possible that two different programs inserting records into the same RMSfile might attempt to use the same unused slot at the same time. However, the location is not known to the programs until the record is actually inserted into the RMSfile.
Your program typically has no knowledge of the access method of an RMSfile or the record to be used on the next insertion. The insert record locking routines take this into account by ensuring that only one program at a time adds a record to an RMSfile. This prevents two programs from inserting records in the same location. Locking an RMSfile for inserting records does not interfere with locking any existing records in the same file. Existing records can be locked while an RMSfile is locked for inserting records.
The first function for insert locking is dilock(C-3). Calling this function attempts to lock an RMSfile for inserting records. Other programs attempting to lock the same RMSfile for inserting records will be notified that they must wait. A sample call to dilock might be:
locked = dilock (sub);
If the RMSfile was not locked for inserting records prior to the call to dilock, a 1 is returned by dilock. This means that all other programs attempting to lock the same RMSfile for inserting records will be refused. Other programs can lock existing records in the same RMSfile. Dilock returns a zero if another program has already locked the RMSfile using dilock or dilockw. At this point the program can wait and try again, or it can notify the user that the RMSfile is busy, and the user must try the operation again. Dilock always returns immediately to the calling program. It does not wait if the RMSfile is locked. Instead, an error is returned.
Dilockw(C-3) is identical to dilock except that it waits if the RMSfile is locked for inserting records. It does not return until the RMSfile is locked. A sample call to dilockw might be:
locked = dilockw (sub);
Normally, dilockw returns a 1 indicating that the record is locked. However, it is possible because of some error conditions that dilockw would return an error code of zero, so the return value should always be checked. The dilockw function attempts to discover deadlock conditions and returns a zero if a deadlock would occur by waiting to lock the RMSfile for inserting records.
Diunlock(C-3) unlocks an RMSfile that has been locked for inserting records by either dilock or dilockw. Calling this function removes the lock placed on the RMSfile by the calling program. Previously the program must have successfully locked the RMSfile for inserting records. A sample call to diunlock might be:
unlocked = diunlock (sub);
This allows other users to lock the RMSfile for insertions.