DosCancelLockRequest

Cancels an outstanding DosSetFileLocks request.

Syntax
DosCancelLockRequest(hFile, pflLock)

Parameters

 * hFile (HFILE) - input: File handle used in the DosSetFileLocks function that is to be cancelled.
 * pflLock (PFILELOCK) - input: Address of the structure describing the region to be locked by DosSetFileLocks.

Return Code

 * ulrc (APIRET) - returns:DosCancelLockRequest returns one of the following values:
 * 0 NO_ERROR
 * 6 ERROR_INVALID_HANDLE
 * 87 ERROR_INVALID_PARAMETER
 * 173 ERROR_CANCEL_VIOLATION

Remarks
DosCancelLockRequest allows a process to cancel the lock range request of an outstanding DosSetFileLocks function.

If two threads in a process are waiting on a lock file range, and another thread issues DosCancelLockRequest for that lock file range, then both waiting threads are released.

Not all file-system drivers (FSDs) can cancel an outstanding lock request.

Local Area Network (LAN) servers cannot cancel an outstanding lock request if they use a version of the operating system prior to OS/2 Version 2.00.

Example Code
This example opens a file named "CANLOCK.DAT", locks a block of the data, writes some data to it, and then cancels the lock request. 
 * 1) define INCL_DOSFILEMGR      /* File Manager values */
 * 2) define INCL_DOSERRORS       /* DOS Error values    */
 * 3) include 
 * 4) include 
 * 5) include 

int main(VOID) {

HFILE    FileHandle   = NULLHANDLE;  /* File handle */ ULONG    Action       = 0,           /* Action taken by DosOpen */ Wrote       = 0;           /* Number of bytes written by DosWrite */ CHAR     FileData[40] = "Forty bytes of demonstration text data\r\n"; APIRET   rc           = NO_ERROR;    /* Return code */

FILELOCK LockArea     = {0},         /* Area of file to lock */ UnlockArea  = {0};         /* Area of file to unlock */

rc = DosOpen("canlock.dat",                /* File to open */             &FileHandle,                   /* File handle */             &Action,                       /* Action taken */             256L,                          /* File primary allocation */             FILE_ARCHIVED,                 /* File attributes */             FILE_OPEN | FILE_CREATE,       /* Open function type */             OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE,             0L);                           /* No extended attributes */ if (rc != NO_ERROR) {                      /* If open failed */ printf("DosOpen error: return code = %u\n", rc); return 1; }

LockArea.lOffset = 0L;             /* Start locking at beginning of file */ LockArea.lRange = 40L;             /* Use a lock range of 40 bytes       */

rc = DosSetFileLocks(FileHandle,       /* File handle   */                     &UnlockArea,       /* No unlock area */                     &LockArea,         /* Lock current record */                     2000L,             /* Lock time-out value of 2 seconds */                     0L);               /* Exclusive lock, not atomic */ if (rc != NO_ERROR) { printf("DosSetFileLocks error: return code = %u\n", rc); return 1; }

rc = DosWrite(FileHandle, FileData, sizeof(FileData), &Wrote); if (rc != NO_ERROR) { printf("DosWrite error: return code = %u\n", rc); return 1; } /* Should check if (rc != NO_ERROR) here... */

rc = DosCancelLockRequest(FileHandle, &LockArea); if (rc != NO_ERROR) { printf("DosCancelLockRequest error: return code = %u\n", rc); return 1; } rc = DosClose(FileHandle); /* Should check if (rc != NO_ERROR) here... */

return NO_ERROR; } 

Related Functions

 * DosSetFileLocks