Set an exclusive lock.
long LOCK_cobfa ( const unsigned long *timeout, /* wait time */ unsigned long *errcode /* error code */ );
Description
In a multithread environment, exclusive control is required to prevent multiple threads from accessing a file simultaneously in the COBOL runtime system.
This function sets the exclusive lock of a COBOL file accessed by the COBOL runtime system to prevent other threads from accessing the COBOL file. When a file is accessed in a multithread environment, this function is used to prevent conflicts.
Specify the number of milliseconds to wait in <*timeout>. If the exclusive lock of a file has been set by another thread and does not open the file before this function is called by another thread <*timeout>, execution of the called function fails. If NULL is specified for <timeout>, the wait time is unlimited.
When the return value of this function is -1, the Windows system error code is set in error code <*errcode>. If NULL has been specified for <errcode>, no value is returned for <*errcode>. The value is unpredictable when the return value of this function is not -1.
Execution Conditions
Always accessible.
Return Values.
Condition | Return value | Meaning |
|---|---|---|
Successful | 0 | Exclusive lock of a COBOL file is successful |
1 | Exclusive lock of a COBOL file is successful. Since the thread exclusively locking the file is terminated without unlocking the file, the thread may be terminated abnormally. Proceed with caution | |
Failed | -1 | System error occurred. Windows system error code is set in <*errcode>. |
-2 | The wait time specified in "<*timeout>" has been exceeded. Access is not locked |
How to use
Execute this function before executing an API function having an I-O function or an API function for obtaining file information. After executing either of these API functions, execute the API function for obtaining a status report, if necessary. Then execute "3.25 UNLOCK_cobfa()" to release the exclusive lock.
While an exclusive lock is held other threads may rewrite the status value. Consequently, to ensure accuracy of the status value, "3.18 cobfa_stat()" must be executed immediately following any I-O related API function.
An example of exclusive control for each I-O is provided below.
long ret, fd, eno, stat, recnum;
ret = LOCK_cobfa ( NULL, NULL ); /* Set the exclusive lock of a file */
if ( ret < 0 ) { .... /* Error processing */ }
fd = cobfa_open ( "file.rel", FA_INPUT | FA_RELFILE | FA_FIXED, 10 );
stat = cobfa_stat ( );
eno = cobfa_errno ( );
UNLOCK_cobfa ( NULL ); /* Open the exclusive lock of a file */
if ( eno == FA_EFNAME ) {
printf ( "errno: %d, stat: %d\n", eno, stat );
...
}
.... /* Perform processing not related to the input-output file */
ret = LOCK_cobfa ( NULL, NULL ); /* Lock file access exclusively. */
if ( ret < 0 ) { .... /* Error processing */ }
cobfa_rdnext ( fd, FA_NEXT, buff );
recnum = cobfa_recnum ( );
UNLOCK_cobfa ( NULL ); /* Perform processing not related to the input/output file */
num = recnum;
.... /* Set the exclusive lock of the file */
ret = LOCK_cobfa ( NULL, NULL ); /* Lock file access exclusively */
if ( ret < 0 ) { .... /* Error processing */ }
cobfa_close ( fd );
UNLOCK_cobfa ( NULL ); /* Open the exclusive lock of the file */A COBOL file can be controlled exclusively from the start to the end of file access. Arbitrary range extension of exclusive control is possible.
An example of continuous exclusive control is provided below.
long ret, fd;
ret = LOCK_cobfa ( NULL, NULL ); /* Set the exclusive lock of a file */
if ( ret < 0 ) { .... /* Error processing */ }
fd = cobfa_open ( "file.seq", FA_OUTPUT | FA_SEQFILE | FA_FIXED, 10 );
cobfa_wrnext ( fd, buffer, 10 );
.... /* Perform input-output operation for files */
cobfa_close ( fd );
UNLOCK_cobfa ( NULL ); /* Open the exclusive lock of a file */