Managing with Local RINs

A RIN used to manage a resource being shared by related processes is called a local RIN. You use local RINs to prevent simultaneous access to a resource by two or more processes in the same job/session. Each local RIN is a positive integer that is unique within your job/session.

Local RINs are assigned with the GETLOCRIN intrinsic, managed with the LOCKLOCRIN and UNLOCKLOCRIN intrinsics, and released with the FREELOCRIN intrinsic.

Acquiring Local RINs

You must acquire local RINs with the GETLOCRIN intrinsic before you can use them within your job/session. The following intrinsic call,

     GETLOCRIN (6);

acquires six local RINs, RIN numbers 1 through 6, that can be used by the calling process as well as other processes in the same job/session.

All local RINs you are planning to use in your program must be acquired in just one call to GETLOCRIN. If your program requires additional local RINs after the initial GETLOCRIN call, you must first release all local RINs then acquire the new number of local RINs with another GETLOCRIN call.

Locking and Unlocking Local RINs

You can lock a local RIN using the LOCKLOCRIN intrinsic. Once your process has successfully locked the RIN, no other process can lock the same local RIN until your process unlocks it with the UNLOCKLOCRIN intrinsic.

While you have the local RIN locked, exclusive access is guaranteed only if other processes first attempt to lock the local RIN prior to accessing the resource associated with the locked RIN.

A local RIN, acquired by your program, can be locked and unlocked by any process in your program's process structure.

Following is an example of a LOCKLOCRIN intrinsic call from a program that has previously acquired local RINs 1 through 4:

          . 

          . 

          . 

     RINNUM := 4; 

     LOCK := 1; 

     LOCKLOCRIN (RINNUM,LOCK); 

          . 

          . 

          .

The parameters specified in the example are described below.

`RINNUM`	Passes the local RIN number associated with the resource you wish exclusive access to. The value 4 is a local RIN returned by the `GETLOCRIN` intrinsic.
`LOCKCOND`	`LOCKCOND` passes a value indicating the following: if the local RIN is currently locked by another process, control does not return to your program from the `LOCKLOCRIN` call until the local RIN is again available and successfully locked by your process.

You use the UNLOCKLOCRIN intrinsic to unlock a local RIN that has been previously locked by the calling process.

Example 2-4 illustrates how the LOCKLOCRIN and UNLOCKLOCRIN intrinsics can be used by two processes executing in the same job/session. Assume that both the parent process (PARENT) and the child process (CHILD) are executing concurrently, line by line.

Figure 2-4 Figure 2-4.

     PARENT PROCESS                     CHILD PROCESS 



{  PARENT BEGINS EXECUTION    } 

          . 

          . 

          . 

     HPFOPEN (LP,STATUS,...); 

     GETLOCRIN (3); 

     LPRIN := 1; 

     FWRITE (LP,...); 

     CREATE (PROGNAME,,CHILD...); 

     LOCKLOCRIN (LPRIN,1); 

     ACTIVATE (CHILD);                  {   CHILD BEGINS EXECUTION    } 

     FWRITE (LP,...);                             . 

          .                                       . 

          .                                  LPRIN := 1; 

          .                                  HPFOPEN (LP,STATUS,...); 

          .                                  LOCKLOCRIN (LPRIN,1); 

          .                                                             

          .                              CHILD IS BLOCKED WHEN IT       

          .                              ATTEMPTS TO LOCK RIN.          

          .                                                             

          .                              EXECUTION CONTINUES WHEN RIN   

          .                              IS UNLOCKED BY PARENT AND      

          .                              LOCKED BY CHILD.               

     UNLOCKLOCRIN (LPRIN);                                              

          .                                       . 

     LOCKLOCRIN (LPRIN,1);                        . 

                                                  . 

 PARENT IS BLOCKED WHEN IT                   FWRITE (LP,...); 

 ATTEMPTS TO LOCK RIN.                            . 

                                                  . 

 EXECUTION CONTINUES WHEN RIN                     . 

 IS UNLOCKED BY CHILD AND                         . 

 LOCKED BY PARENT.                                . 

                                             UNLOCKLOCRIN (LPRIN); 

     FWRITE (LP,...);                             . 

          .                                       . 

          .                                       . 

          .                                       .

Example 2-4.  Locking and Unlocking Local RINs.

In Example 2-4, both processes have agreed to RIN management, associating RIN 1 (designated in the program as LPRIN) with a line printer (designated as LP). When PARENT first accesses LP, CHILD has not been created, and so RIN management is not yet required.

To guarantee exclusive access to LP first, PARENT locks LPRIN before CHILD is activated. When PARENT finishes with LP, it unlocks LPRIN, thus making LPRIN available to be locked. In this case, CHILD has been blocked and is waiting for LPRIN to become available.

When CHILD attempts to lock LPRIN, CHILD passes a value to LOCKLOCRIN indicating that execution should be blocked until LOCKLOCRIN can successfully return the locked RIN. The blocking occurs because PARENT currently has LPRIN locked. Execution continues only when PARENT unlocks LPRIN, thus making RIN 1 available to be locked by CHILD. While CHILD has LPRIN locked, PARENT is unable to lock LPRIN until it is unlocked by CHILD.

Releasing Local RINs

You can use the FREELOCRIN intrinsic to release all local RINs your program previously acquired with GETLOCRIN. Following is an example of a call to FREELOCRIN:

     FREELOCRIN;

Any process in your program's process structure can release local RINs. If you do not use FREELOCRIN to release local RINs, they are released to MPE XL when your program terminates.

Identifying a Local RIN Locker

The LOCRINOWNER intrinsic identifies the process in your program's process structure that has a particular local RIN locked. If the RIN is locked by the parent of the calling process, LOCRINOWNER returns a zero. If the RIN is locked by any other process, LOCRINOWNER returns the Process Identification Number (PIN) of that process.

Knowing the identity of the locking process is useful when parent and child processes are synchronizing access to one another through calls to the ACTIVATE and SUSPEND intrinsics.

Example 2-5 is an example of RIN management where a parent process (PARENT) acts as a monitor for several child processes (one of whom is identified as CHILD1). Assume that both PARENT and CHILD1 are executing concurrently, line by line.

Note that two agreements have been made by the programmer regarding RIN management prior to writing the code in Example 2-5.

When a child process wishes to communicate with PARENT it must first successfully lock local RIN 1 (designated in the program as WHICHCHILD). This guarantees that other child processes cannot interfere in the communication being performed while local RIN 2 (designated as SYNCHRIN) is locked.
A child process must successfully lock local RIN 2 only after it has successfully locked local RIN 1. PARENT locks RIN 2 to guarantee that the child process that activated PARENT is suspended while PARENT executes code in the WHILE loop.

Figure 2-5 Figure 2.5



  PARENT PROCESS                     CHILD PROCESS 



{ PARENT EXECUTING     }              {    CHILD EXECUTING     } 

         .                                        . 

    GETLOCRIN (2);                                . 

         .                              LOCKLOCRIN (WHICHCHILD,1); 

    CHILDCOUNT := 0;                    LOCKLOCRIN (SYNCHRIN,1); 

    WHILE CHILDCOUNT <= MAXCOUNT DO               . 

    BEGIN                                         . 

    SUSPEND (CHILDWAIT,SYNCHRIN);                 . 

                                                  . 

      PARENT IS SUSPENDED                         . 

       UNTIL ACTIVATED                            . 

        BY A CHILD                                . 

                                        PARENT := FATHER; 

                                        ACTIVATE (PARENT); 

       .                                SUSPEND (PARENTWAIT,SYNCHRIN); 

    LOCKLOCRIN (SYNCHRIN,1);                                          

    OWNER := LOCRINOWNER (WHICHCHILD);     CHILD1 IS SUSPENDED        

       .                                     UNTIL ACTIVATED          

       .                                        BY PARENT             

     CHILDCOUNT := CHILDCOUNT + 1;                                    

     ACTIVATE (OWNER);                                                

    END; {WHILE LOOP}                             . 

       .                                UNLOCKLOCRIN (WHICHCHILD); 

       .                                          . 

       .                                          .

Example 2-5.  Identifying a Local RIN Locker. 

Both processes in Figure 2-5 share the following constants:

`WHICHCHILD` = 1	All processes in the program example agree that `WHICHCHILD` is the local RIN used to determine the identity of the child process that activated the parent process `PARENT`.
`SYNCHRIN` = 2	All processes in the program example agree that `SYNCHRIN` is the local RIN used to ensure that `PARENT` can execute required code located in the WHILE loop before another child process can activate it.
`PARENTWAIT` = 1	Used by both `SUSPEND` and `ACTIVATE` to indicate that the suspended process permits only its parent process to activate it with an `ACTIVATE` intrinsic call.
`CHILDWAIT` = 2	Used by both `SUSPEND` and `ACTIVATE` to indicate that the suspended process permits only a child process to activate it with an `ACTIVATE` intrinsic call.

In Example 2-5, PARENT waits in a suspended state, unable to execute until an activation signal is received from a child process (in this case, by CHILD1 calling ACTIVATE). Once activated, PARENT locks SYNCHRIN to synchronize its communication with CHILD1. LOCRINOWNER determines the identity of the process that activated PARENT (the process that locked WHICHCHILD). PARENT then performs its required duty within the WHILE loop.

PARENT activates the process that activated PARENT (CHILD1) then suspends itself to again await activation by a child process. Note that SYNCHRIN is passed as a parameter to SUSPEND. SUSPEND releases the RIN, making SYNCHRIN available to be locked by other processes.

For details on using SUSPEND and ACTIVATE, refer to the discussion of suspending and activating processes in Process Management Programmer's Guide (32650-90023).

Managing with Local RINs

Technical documentation

» Table of Contents

» Index

Acquiring Local RINs

Locking and Unlocking Local RINs

Releasing Local RINs

Identifying a Local RIN Locker