Novell Documentation: NLM & NetWare Libraries for C

NWOpenSemaphore

Creates and initializes a named semaphore to the indicated value

Local Servers:blocking
Remote Servers:blocking
NetWare Server:3.11, 3.12, 3.2, 4.x, 5.x, 6.x
Platform:NLM, Windows NT, Windows 95, Windows 98
Library:Cross-Platform NetWare Calls (CAL*.*)
Service:Synchronization

Syntax

  #include <nwsync.h> 
  or 
  #include <nwcalls.h> 
   
  N_EXTERN_LIBRARY(NWCCODE)NWOpenSemaphore ( 
     NWCONN_HANDLE       conn,  
     const nstr8 N_FAR  *semName,  
     nint16              initSemHandle,  
     pnuint32            semHandle,  
     pnuint16            semOpenCount);

Delphi Syntax

  uses calwin32 
   
  Function NWOpenSemaphore 
    (conn : NWCONN_HANDLE; 
     const semName : pnstr8; 
     initSemHandle : nint16; 
     semHandle : pnuint32; 
     semOpenCount : pnuint16 
  ) : NWCCODE;

Parameters

conn: (IN) Specifies the NetWare server connection handle.
semName: (IN) Points to the name of the semaphore to be opened.
initSemHandle: (IN) Specifies the number of tasks that can simultaneously access the resources to which the semaphore is tied.
semHandle: (OUT) Points to the NetWare semaphore handle.
semOpenCount: (OUT) Points to the number of stations that currently have this semaphore open (optional; set to NULL if you do not wish this number to be returned).

Return Values

These are common return values; see Return Values (NDK: Connection, Message, and NCP Extensions) for more information.

0x0000	SUCCESSFUL
0x8801	INVALID_CONNECTION
0x890A	NLM_INVALID_CONNECTION
0x8996	SERVER_OUT_OF_MEMORY
0x89FF	LOCK_ERROR

Remarks

Calling NWOpenSemaphore increments the semOpenCount counter. If the semaphore exists, initSemHandle is ignored. The handle returned must be used to access the semaphore. Only the first application to open the semaphore (and thus create the semaphore) can set the initial value in initSemHandle.

NWOpenSemaphore is usually called by setting initSemHandle to a value other than 0. If initSemHandle is set to 0, consider the following items:

Semaphore ownership will not be established until the semaphore is signaled.
The semaphore cannot be used until it is first signaled by an application.
Usually semaphore applications loop from waiting on a semaphore to signaling the semaphore. If initSemHandle is 0, the semaphore must be signaled from outside the wait/signal loop.

NWWaitOnSemaphore decrements the semaphore value by 1 if it is greater than 0. If the semaphore value and the timeOutValue parameter are both 0, a time out failure (LOCK_ERROR) will be returned.

NWSignalSemaphore increments the semaphore value by 1.

NCP Calls

0x2222 32 Open Semaphore