PillarSoft

Contributed by: Doug Rickman, Global Hydrology and Climate Center, MSFC, NASA

This is aimed at intermeditate REXX users.

This is a shell that uses mutex semaphores. It shows how to call them and displays the return codes generated.

/* a shell for use of Mutex semaphores                                       */
/*                                                                           */
/* Doug Rickman October 12, 1997                                             */

signal on Halt
signal on NotReady

if rxfuncquery('rexxlibregister') then do         /* this will start rexxlib */
    call rxfuncadd 'rexxlibregister', 'rexxlib', 'rexxlibregister' 
    call rexxlibregister
    end
if rxfuncquery('sysloadfuncs') then do           /* this will start rexxutil */
    CALL RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
    CALL SysLoadFuncs
    end

/* --------------------------------------------------------------------------*/
/* --- begin MAIN                                               -------------*/

semName='\sem32\test'
timeout=10000

say 'Start time = 'time('E')

say 'Query 1.  Does the semaphore exist?'
rc=mutexquery(semName)
say

say 'Ask for the semaphore, if it does not exist create it.'
if MUTEXREQUEST(semName,100)=187 then rc=MutexCreate(semName)
say

say 'Query 2.  Show that it does now exist.'
rc=mutexquery(semName)

/* Delay, so something else can start and try to grab the semaphore. */
timeout=5
/* say 'Waiting 'timeout' seconds' */
rc=delay(timeout)
say

say 'Ask for the semaphore again.  Try 2.'
rc=MUTEXREQUEST(semName,timeout)
say

say 'Query 3.  Does the semaphore exist?'
rc=mutexquery(semname)
say

say 'Release the semaphore.'
rc=mutexrelease(semName)
say

say 'Close the semaphore.'
rc=mutexclose(semName)

say 'Elapsed time = 'time('E')
return 1

/* --- end MAIN                                                 -------------*/
/* --------------------------------------------------------------------------*/

/* --------------------------------------------------------------------------*/
/* --- begin subroutine - MutexRequest:                         -------------*/
MutexRequest: procedure
semName=arg(1)
timeout=arg(2)
rc= MUTEXSEM_REQUEST(semName,timeout)
select
    when rc=0 then say 'the MUTEXSEM_REQUEST operation was successful'
    when rc=95 then say 'interrupt occurred '
    when rc=103 then say 'too many semaphore requests outstanding '
    when rc=105 then say 'semaphore owner died '
    when rc=123 then say 'name "'semName'"is invalid (must begin with "\sem32\")'
    when rc=187 then say 'semaphore "'semName'" does not exist'
    when rc=640 then say 'timeout occurred after 'timeout' milli-seconds'
    otherwise say 'Something is wrong, the rc for the MUTEXSEM_REQUEST is 'rc',',
               ||' which is not understood.'
    end /* select */
return rc
/* --- end soubroutine - MutexRequest:                          -------------*/
/* --------------------------------------------------------------------------*/
/* --------------------------------------------------------------------------*/
/* --- begin subroutine - MutexQuery:                           -------------*/
MutexQuery: procedure
semName=arg(1)
rc=MUTEXSEM_QUERY(semName)
select
    when rc<0 then
    select
        when rc=-105 then say 'semaphore owner died '
        when rc=-123 then say 'name: 'semName' is invalid (must begin with "\sem32\")'
        when rc=-187 then say 'semaphore "'semName'" does not exist '
        otherwise say say 'Something is wrong, the rc for the MUTEXSEM_QUERY is 'rc',',
                         ||' which is not understood.'
        end /* select */

    when rc='0 0 0' then say 'The semaphore "'semName'" is un-owned'
    otherwise do
        parse var rc Requests PID TID
        say 'There is/are 'Requests' request outstanding from process ID= 'PID',',
        ||' thread ID= 'TID
        end
    end /* select */
return rc
/* --- end soubroutine - MutexQuery:                            -------------*/
/* --------------------------------------------------------------------------*/

/* --------------------------------------------------------------------------*/
/* --- begin subroutine - MutexCreate:                          -------------*/
MutexCreate: procedure
semName=arg(1)
rc= MUTEXSEM_CREATE(semName)
select
    when rc=0   then say 'the MUTEXSEM_CREATE operation was successful '
    when rc=123 then say 'MUTEXSEM_CREATE error - name: 'semName' is invalid ',
                      ||'(must begin with "\sem32\")'
    when rc=285 then say 'MUTEXSEM_CREATE error - named semaphore: "'semName'" already exists '
    otherwise  say 'Something is wrong, the rc for the MUTEXSEM_CREATE is 'rc',',
                ||' which is not understood.'
    end /* select */
return rc
/* --- end soubroutine - MutexCreate:                           -------------*/
/* --------------------------------------------------------------------------*/

/* --------------------------------------------------------------------------*/
/* --- begin subroutine - MutexRelease:                         -------------*/
MutexRelease: procedure
semName=arg(1)
rc=MUTEXSEM_RELEASE(semName)
select
    when rc=  0 then say 'The MUTEXSEM_RELEASE operation was successful'
    when rc=105 then say 'semaphore owner died '
    when rc=123 then say 'MUTEXSEM_RELEASE error - name: 'semName' is invalid ',
                      ||'(must begin with "\sem32\")'
    when rc=187 then say 'MUTEXSEM_RELEASE error - semaphore "'semName '" does not exist '
    when rc=288 then say 'semaphore "'semName '" not owned by requester '
    otherwise say 'Something is wrong, the rc for the MUTEXSEM_RELEASE is 'rc',',
                ||' which is not understood.'
    end /* select */
return rc
/* --- end soubroutine - MutexRelease:                              -------------*/
/* --------------------------------------------------------------------------*/

/* --------------------------------------------------------------------------*/
/* --- begin subroutine - MutexClose:                           -------------*/
MutexClose: procedure
semName=arg(1)
rc=MUTEXSEM_CLOSE(semName)
select
    when rc=0   then say 'The MUTEXSEM_CLOSE operation was successful'
    when rc=123 then say 'MUTEXSEM_CLOSE error - name: 'semName' is invalid ',
                      ||'(must begin with "\sem32\")'
    when rc=187 then say 'Semaphore "'semName '" does not exist '
    when rc=301 then say 'MUTEXSEM_CLOSE error - Semaphore "'semName '" has not been released.'
    otherwise  say 'Something is wrong, the rc for the MUTEXSEM_CLOSE is 'rc',',
                ||' which is not understood.'
    end /* select */
return rc
/* --- end soubroutine - MutexClose:                                -------------*/
/* --------------------------------------------------------------------------*/

/* --------------------------------------------------------------------------*/
/* --- begin subroutine - Halt:                                 -------------*/
Halt:
say 'This is a graceful exit from a Cntl-C'
exit
/* --- end  subroutine - Halt:                                  -------------*/
/* --------------------------------------------------------------------------*/
/* --- begin subroutine - NotReady:                             -------------*/
NotReady:
say 'It would seem that you are pointing at non-existant data.  Oops.  Bye!'
exit
/* --- end  subroutine - NotReady:                              -------------*/
/* --------------------------------------------------------------------------*/