DosCancelLockRequest

From EDM2
Jump to: navigation, search

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.

#define INCL_DOSFILEMGR       /* File Manager values */
#define INCL_DOSERRORS        /* DOS Error values    */
#include <os2.h>
#include <stdio.h>
#include <string.h>

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