Synopsis: 

       sem_set(sem_id)

Arguments:

       sem_id - The semaphore ID.

       

Description:   The first task that calls this function will cause the value of the specified semaphore (sem_id) to be set and the function will return 1 to indicate that the calling task sucessfully caused the semaphore to be set.       If the semaphore had already been set by another task then the semaphore will remain unchanged and the calling task will block and will be entered into a queue waiting for the semaphore to be cleared.          When the calling task reaches the top of the queue and sets the semaphore the task will be unblocked and the function will return 1.

Note that this function also carries out a rudimentary check for deadlock.    If an attempt to set a semaphore is carried out by a task (task 1), but the semaphore has already been set by another task (task 2),  then before putting task 1 into a blocking state a check is made to ensure that task 2 isn't already waiting on a semaphore that has been set previously by task 1 (deadlock condition).       If this condition is found the then function will output an error message and will return -2.

Note that if a task is killed (either through an external kill command, a stop statement, a restart statemetn or by chaining to another task) then all semaphore that the task had previously set will be cleared and it will be removed from any queues waiting for semaphores.

Returns:    1 if the semaphore was successfully set by the calling task, -1 if an invalid semaphore ID is specified,  -2 if a deadlock condition would have occurred if the task had blocked.