HP 3000 Manuals HP 3000 Manuals
Facilities in Multi-User Micro Focus COBOL In a multi-user environment, the default data locking for files opened for I-O is exclusive locking. This sort of locking requires no extra syntax. By using the compiler options AUTOLOCK or FILESHARE you can change the default locking to automatic locking of single records, without any extra syntax in your program. You can obtain more sophisticated locking on a single record or a group of records if you include extra syntax in your program. Depending on the organization of the shared files, there are different syntax and programming considerations. The sections that follow describe how to program for shared sequential or line sequential files, relative files, and indexed sequential files. Data Locking There are three types of data locking: * Automatic * Manual * Exclusive Automatic locking Automatic locking is used to lock a single record or multiple records. Automatic single record locks mean that when the program reads a record from a file opened for I-O, that record is automatically locked until the program next accesses that file. For files that have been opened for INPUT, records are never locked. Files opened for OUTPUT cannot support automatic locking, and always hold an exclusive lock on the whole file. Your program cannot access a file in automatic (shareable) mode if another operator has already opened the file in exclusive mode. Automatic multiple record locks mean that you can lock records up to the limit for your implementation. These records are locked automatically as they are read, and are not released until a CLOSE, UNLOCK or COMMIT statement is executed. When the WRITELOCK or FILESHARE compiler option is specified, WRITE and REWRITE statements also acquire a record lock when you are locking multiple records. See Appendix G , Directives for Compiler/Generator for details of these directives. Manual locking Manual locking is used to lock a single record or multiple records. Record locking is similar to automatic, except that to lock a record you must explicitly lock it when it is read. That is, you must specify READ WITH LOCK (single records) or READ WITH KEPT LOCK (multiple records) to acquire a lock. As with automatic, only files opened for I-O can acquire record locks. In addition, with multiple records WRITE and REWRITE statements also acquire a lock if you have specified the WRITELOCK or FILESHARE compiler option. Exclusive locking Exclusive locking means that the whole of the file is locked as soon as the operator executes an OPEN statement on the file. Your program cannot open a file in exclusive mode if another operator is already accessing the file. To obtain an exclusive lock on a file, you must have READ and WRITE permissions for that file. With exclusive locking, the file remains locked until it is closed. If your program opens a data file for OUTPUT, this implies an exclusive lock on the file. If your program opens a relative or indexed file for EXTEND, this implies an exclusive lock on the file. In a multi-user environment each operator can open more than one data file, and each operator may have access to the same data files as other operators. A file that is shareable can be accessed by one or more programs, each locking one record in the file or multiple records in the file. Figure Figure 16-4 shows an hypothetical multi-user environment.Figure 16-4. A Typical Multi-User Environment Record Sequential and Line Sequential Files. When your program uses record sequential files you can lock only individual records or whole files. You cannot lock groups of records. When your program uses line sequential files there is no record locking at all, only file locking. The FILE-CONTROL paragraph for record sequential and line sequential files is detailed and explained in General Rules 1 and 2 in the section FILE-CONTROL Entry in the Language Reference. Each time your program accesses a file with an OPEN, READ or READ WITH LOCK statement the file locking you have specified is taken into account. See the Language Reference for details of these statements. This means that: * For Record Sequential and Line Sequential Files: * When you specify LOCK MODE IS EXCLUSIVE, the whole file is locked from the time your program opens the file unless the file has been opened for INPUT. In this case other operators will still be able to access the file and to read it, provided they have both READ and WRITE access to the file, but the EXCLUSIVE lock will prevent them from modifying it in any way. * When you do not specify a LOCK MODE IS clause, the default locking is used. Files opened for INPUT are shareable. Files opened for OUTPUT, I-O or EXTEND are exclusive. * For Record Sequential Files: * When you specify LOCK MODE IS AUTOMATIC a single record is locked as the program reads it. * When you specify LOCK MODE IS MANUAL single records are locked as the user executes a READ WITH LOCK on the record. Relative Files. When your program uses relative files you can lock whole files, single records or groups of records up to the maximum allowed by your implementation. The FILE-CONTROL paragraph for relative files is detailed and explained in General Format 3 in the section FILE-CONTROL Entry in your Language Reference. You can lock several records simultaneously with the WITH LOCK ON MULTIPLE RECORDS clause. Once you have locked the maximum number of records allowed by your implementation, a status of "Too many locks" is returned if you try to lock any more records. When this happens you must close the file or execute a COMMIT statement or an UNLOCK statement to release these records. Both MANUAL and AUTOMATIC locking can be performed on files with both single record locking and multiple record locking. Each time a file is accessed with an OPEN, READ, READ WITH LOCK, READ WITH KEPT LOCK, WRITE or REWRITE statement the file locking you have specified is taken into account (see the Language Reference for details). This means that: * When you specify LOCK MODE IS EXCLUSIVE, the whole file is locked from the time your program opens the file. In this case other operators will still be able to access the file and to read it, provided they have both READ and WRITE access to the file, but the EXCLUSIVE lock will prevent them from modifying it in any way. * When you specify LOCK MODE IS AUTOMATIC, a single record is locked as the program reads it. * When you specify LOCK MODE IS AUTOMATIC WITH LOCK ON MULTIPLE RECORDS, multiple records are locked as the operator executes READ statements. Records remain locked until the file is closed, or a COMMIT statement or an UNLOCK statement is executed. * When you specify LOCK MODE IS MANUAL, single records are locked as the user executes a READ WITH LOCK on the record. * When you specify LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS, multiple records are locked as the operator executes READ WITH KEPT LOCK statements. Records remain locked until the file is closed, or a COMMIT statement or an UNLOCK statement is executed. * When you do not specify a LOCK MODE IS clause, the default locking is used. Files opened for INPUT are shareable, files opened for OUTPUT, I-O or EXTEND are exclusive. Note that although the default locking for files opened EXTEND is exclusive this may change in future releases of the product. Thus we recommend that you explicitly specify locking in your programs for files which you wish to open EXTEND. When your program is locking multiple records you can also acquire a record lock on a WRITE or REWRITE statement. To do this you must specify the WRITELOCK or FILESHARE compiler option when you submit your program to the this COBOL system. See Appendix G , Directives for Compiler/Generator for details of these options. Unless you explicitly include WITH LOCK ON MULTIPLE RECORDS, single record locks are assumed when the lock is automatic or manual. Indexed Sequential Files. With indexed sequential files you can lock whole files, single records or groups of records up to the maximum allowed by your implementation. The FILE-CONTROL paragraph for indexed sequential files is detailed and explained in General Format 4 of the section FILE-CONTROL Entry in your Language Reference. As with relative files, the WITH LOCK ON RECORD or WITH LOCK ON MULTIPLE RECORDS is the way you specify single or multiple record locking respectively. You can lock single or multiple records in either MANUAL or AUTOMATIC lock mode. Note that you can OPEN an indexed sequential file only if you have WRITE permission to the index portion of the file. All File Types. Multiple OPEN requests within the same run unit can have conditions applied to determine whether or not a given file has been previously opened and whether any such open was exclusive. This functionality is available when file opens are issued from separate source programs. Any attempt to open a file multiple times in the same source program results in a "File already open - cannot be opened" error. This feature is enabled by setting the value of the same_proc_excl_detection COBCONFIG run-time configurable to TRUE. See Chapter 31 , Run-Time Configuration for further information on this and other run-time configurables. Procedure Division Entry for Multi-User Environments Generally, multi-user Micro Focus COBOL does not require any extra considerations in your procedure division. The exception to this is checking the file status for a lock condition (refer to the section "File Status" later in this chapter). There are, however, some instances when you need to use different syntax in your procedure division. That syntax is described below. * The COMMIT statement This statement releases record locks on all records in all the files the operator has opened. This includes SEQUENTIAL, RELATIVE and INDEXED files, with automatic or manual locking on single and multiple records. The COMMIT statement has no effect at all on exclusive files. * The UNLOCK statement The UNLOCK file-name statement releases all record locks the operator has acquired on the specified file. You may use this statement only for files which are shareable. * The READ statement With shareable files opened for I-O whose LOCK MODE is MANUAL, you must include the WITH LOCK phrase (for single record locks) or WITH KEPT LOCK phrase (for multiple record locks). Additionally, with shareable files with multiple record locking the REWRITE and WRITE statements may also lock the record that is accessed. REWRITE and WRITE statements lock records if the WRITELOCK or FILESHARE compiler option is specified. Your Language Reference contains details of the syntax mentioned here. File Status. In Chapter 18 , File Status, the section Input-Output Error Handling explains how to set up a file status item with the FILE STATUS IS data-name clause in the FILE-CONTROL paragraph. In a multi-user environment you use this status item to check the status of an attempted access to a file. This section explains how to interpret the status codes returned in data-name. The data-name you specify must be a two-character alphanumeric data item. The first character of data-item is called status key 1, and reports generally on the success or failure of an input-output operation on a file. The second character of data-name is status key 2, and if any further information is available it is returned in status key 2. You may want to redefine the status key 2 as a PIC 9(4) COMP item so that this data item can hold the error numbers produced by this COBOL system's Run-Time System. The values that may be returned in these status keys are documented in the Error Messages manual. Additionally, where status key 1 contains the value 9 (operating system error message), status key 2 can contain any of the following values that are specific to a multi-user environment: 65 locked file - another program has already accessed the file to the exclusion of other programs 68 locked record - another program has already accessed the record and has locked it 213 too many locks - the program has already acquired the maximum number of locks on the file, and you must now execute a COMMIT, UNLOCK or CLOSE statement to release record locks before continuing You should specifically test for these conditions in your program. If another program has already locked the record your program wants to access, an attempted WRITE, REWRITE or DELETE operation will fail. If your program attempts to read a record already locked by another program, a lock status (error 68) is returned in the file status data item. However, valid data is also returned (unless the operating system does not support this). When a sequential read finds a record lock, the file position indicator is not updated. The START ... KEY IS GREATER THAN statement can be used to skip over locked records in relative or indexed files. However, if you set the +B run-time switch as described in Chapter 7 , Running earlier in this manual, you will be able to read past locked records. This automatically updates the file position indicator. If you want to receive a 00 status when reading a locked record for which you do not want to acquire a lock, you specify the NODETECTLOCK compiler directive. If your program finds a lock on a record that you are attempting to START, the record lock is ignored, and the file position indicator is updated. It is your responsibility to check for status codes, and to decide what action you want your program to take on finding the various status codes. Handling a File or Record Lock. Whenever your program tries to access a file that has been exclusively opened by another program, you must wait until the other program has closed the file before you can access the data in the file. When your program finds a record lock, you must wait until that record has been released before your program can access it successfully. In the case of a program that has locked multiple records, this means waiting until the program executes a COMMIT or UNLOCK statement, or closes the file. If a read is attempted on a file which is OPEN for INPUT or I-O and has no file status item declared, and the record is found to be locked, the read operation is attempted again at one second intervals until the record becomes available, provided you have set the RETRYLOCK compiler directive. You must be aware that this feature can lead to situations where two applications cannot proceed because they are both trying to access records locked by the other. Alternatively you can set the B run-time switch on to skip over the locked record. See Chapter 7 Running earlier in this manual for details of the B run-time switch. See Appendix G , Directives for Compiler/Generator for details of the RETRYLOCK and NODETECTLOCK compiler directives.
![[]](../../pic3k/M013032/FFN173c50.gif)