DosFSRamSemRequest

Bindings:  C, MASM 

This call obtains a Fast-Safe (FS) RAM semaphore and records the current 
owner for potential cleanup by a DosExitList routine. 

 DosFSRamSemRequest     (FSRamSemStructure, Timeout) 
 

 FSRamSemStructure (PDOSFSRSEM) - input 
    Address of the FS RAM Semaphore data structure. The content of this 
    structure is: 

    fs_Length (USHORT) 
       Length in bytes of the FSRamSemStructure; 14 is the only valid 
       value. 

    fs_ProcID (PID) 
       Owning process ID; 0 means the semaphore is not owned. 

    fs_ThrdID (TID) 
       Owning thread ID; 0 means the semaphore is not owned. 

    fs_UseCount (USHORT) 
       Use count.  The number of times the owning thread has issued 
       DosFSRamSemRequest without issuing a corresponding 
       DosFSRamSemClear. 

    fs_Client (USHORT) 
       Is a 16-bit pattern used by the owner of a semaphore to record 
       maintenance information about the resource managed by the 
       semaphore. 

    fs_RAMSem (ULONG) 
       The RAM semaphore data structure used in this request. 

       Before the initial call to DosFSRamSemRequest, this entire 
       structure must be initialized to zero and its length set to 14. 
       Other than fs_Client, the caller should not modify any fields in 
       this structure. 

 Timeout (LONG) - input 
    The number of milliseconds to wait for the semaphore to be cleared 
    before resuming execution. The meaning of the specified values are: 

    Value     Definition 
     -1       The requestor waits indefinitely when the semaphore is 
              owned. There is no time out. 
      0       There is an immediate return if the semaphore is owned. 
    >0        The value is the number of milliseconds to wait, if the 
              semaphore is owned. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    121       ERROR_SEM_TIMEOUT 
 
 Remarks 

 When DosFSRamSemRequest is called, it checks the status of the semaphore. 
  If it is unowned, then DosFSRamSemRequest sets it owned, increments 
 fs_UseCount, and returns immediately to the caller. 

 If the semaphore is owned, the caller has the option to block until the 
 semaphore is no longer owned. The unblocking of a DosFSRamSemRequest is 
 "level triggered" because it does not actually return unless the 
 semaphore remains clear until the affected thread can be redispatched to 
 claim it successfully. The Timeout parameter can be used to place an 
 upper bound on the amount of time to block before returning, even though 
 the semaphore remains owned. 

 When the thread is done with the protected resource, it calls 
 DosFSRamSemClear.  DosFSRamSemClear decrements fs_UseCount. Recursive 
 requests for FS RAM semaphores are supported by the use count, which 
 keeps track of the number of times the owner has issued a 
 DosFSRamSemRequest without a corresponding DosFSRamSemClear. If the call 
 to DosFSRamSemClear decrements the use count to zero, the semaphore is 
 set unowned, and any threads that were blocked waiting for the semaphore 
 resume execution. 

 The 16-bit field fs_Client is not interpreted by the FS RAM semaphore 
 calls.  Instead, it provides the caller with a means of identifying the 
 resource being accessed by the owner of the semaphore.  This field is 
 initialized to zero when a FS RAM semaphore is first acquired.  The owner 
 may place values into this field that describe the resource. These values 
 can be used by an exit list handler to determine the appropriate cleanup 
 action. 

 When a process terminates while owning a FS RAM semaphore, any routines 
 in the exit list maintained by DosExitList are given control. These 
 routines take appropriate steps to guarantee the integrity of resources 
 owned by the process. To clean up a resource protected by a FS RAM 
 semaphore, DosFSRamSemRequest is called to gain ownership of the 
 semaphore.  When issued during exit list processing , DosFSRamSemRequest 
 examines the semaphore to determine if the semaphore is owned by the 
 active process. It then forces the owning thread ID to be equal to the 
 current thread ID and sets 
 fs_Count = 1.  This allows the exit list routine to be programmed without 
 any FS RAM semaphore handling instructions.  When the exit list routine 
 has completed its operations, it restores the resource for use by others 
 by issuing DosFSRamSemClear.