Power-Programmierung/CD1.mdf/lan/semaph/sema.doc

Text File | 1988-08-10 | 5KB | 230 lines

                    Novell NetWare Semaphore Routine
                        Written by Tom Scribner

INTRODUCTION:

Novell's NetWare provides semaphore capability for a variety of
uses.  Several of these uses are in an exclusion mechanism where
record locking cannot be used, multiuser applications, and
program to program notification.   The server maintains a table
where semaphores are placed.  Applications can place a semaphore
onto the table, increment the semaphore count and close the
semaphore.

A good example of semaphores are in a record locking capacity.
Currently DOS does not provide a means of locking a record with
read access; therefore, with several B-Tree, ISAM file management
packages, if a user locked a record (and the index record), then
when another user wished to only read that record, they would be
denied until the lock was freed.  Semaphores can provide the
capability for read-through locks.  The application opens a semaphore
when its intentions are to update a record.  Once the record is
updated, the semaphore is closed.  (NOTE: in order to use this
method effectively, the application must first check to see if this
semaphore is already active).  If the application only wishes to
read the record with no update, no semaphore should be opened.

Semaphores can also provide limited access to programs for multi-
user capability.  If an application is designed for only a 5 station
access, an application can open a semaphore, check its open count,
and if greater than the maximum number of allocated users, can
notify the user and abort.   Several packages on the market today
use this method of limiting the number of users.

If you have a problem, need assistance, or have suggestions, please
contact me via CompuServe.

     Tom Scribner
     CompuServer ID <76154,1265>


NOTE:   These routines were developed with Microsoft V5 C Compiler.
        If you use another version or cannot use functional
        prototypes, remove the definition of MSC5 in the make file.
















                                  Page -1-


NetWare Semaphore Function Call's                       OpenSemaphore
---------------------------------------------------------------------

SUMMARY:

#include <sema.h>

long OpenSemaphore( SemaphoreName, InitValue, &OpenCount)
char *SemaphoreName;          /* Character Name for Sema */
int InitValue;                /* Initial Open Value */
int *OpenCount;               /* Return for open count */

DESCRIPTION:

The OpenSemaphore function places the SemaphoreName in the Server's
semaphore table.  The InitValue is only set the first time the
semaphore is opened.  OpenCount provides the ability to obtain the
number of similarly named semaphores currently open.

RETURN VALUE:

The OpenSemphore returns the semaphore handle used for the other
semaphore functions.  A return value of -1 (ERROR) indicates a
error, and the actual error code is placed into NetError.

EXAMPLE

char *SNAME = {"NET_ISAM"};
int  counter;

long ret_handle;

ret_handle = OpenSemaphore(SNAME,1,&counter);
printf("There are %d users currently in %s\n",counter,SNAME);





















                                Page -2-

NetWare Semaphore Function Call's                    ExamineSemaphore
---------------------------------------------------------------------

SUMMARY:

#include <sema.h>

int ExamineSemaphore( handle )
long handle;            /* Handle returned from OpenSemaphore */


DESCRIPTION:

The ExamineSemaphore function obtains the open count of the named
handle.   The handle used is returned from the OpenSemaphore
function.

RETURN VALUE:

The ExamineSemaphore returns the number of open semaphores. A
return value of -1 (ERROR) indicates a error, with the error
number in NetError;

EXAMPLE:

long shandle;   /* already contains the handle from open semaphore */
int open_users;

open_users = ExamineSemaphore( shandle );
printf("There are %d users in application\n",open_users);


























                                Page -3-


NetWare Semaphore Function Calls                      CloseSemaphore
---------------------------------------------------------------------

SUMMARY:

#include <sema.h>

int CloseSemaphore( handle )
long handle;              /* handle from OpenSemaphore */

DESCRIPTION:

The CloseSemaphore closes the opened semaphore.

EXAMPLE:

long shandle;        /* contains the handle from open semaphore */

if( CloseSemaphore( shandle ) == 0)
        printf("Semaphore closed successfully\n");
else
        printf("Error during closing of semaphore, Error no %d\n",
           NetError);

























                                Page -4-