Managing with Global RINs

A RIN used to manage a resource being shared by unrelated processes is called a global RIN. You use global RINs when you are using RIN management to prevent simultaneous access to a resource by two or more processes that may not be located in the same job/session. Each global RIN is a positive integer that is unique within MPE XL. Global RINs are acquired and released through system commands, and locked and unlocked through system intrinsics.

If your program has only standard user capabilities, it can lock only one global RIN (used at the unrelated process level) at a time. With MR capability, your program can lock two or more global RINs at the same time.

Acquiring Global RINs

You can acquire a global RIN with the :GETRIN command. Following is an example of a :GETRIN call:

     :GETRIN PASSWORD

where PASSWORD is a required password, a character string of up to eight alphanumeric characters, beginning with an alphabetic character. You use the RIN password to restrict the locking of global RINs to authorized users.

Before you and other users can engage in global RIN management you must distribute the global RIN and its password to the other users. The user that acquires the global RIN is considered the owner of that RIN.

You typically enter the :GETRIN command during a session when you decide to use global RINs in your program to manage a resource. As a result of the command, MPE XL makes a global RIN available for use from a pool of free global RINs, and displays the global RIN in the following manner:

     RIN: rinnum

Cooperating processes can use the RIN during the current session or during future jobs/sessions. A global RIN is available even when the owner is logged off. The global RIN is available until the owner of the RIN releases the RIN back to MPE XL with the :FREERIN command.

The total number of global RINs that MPE XL can assign is specified when the system is configured, but can never exceed 1024. If all currently available global RINs are acquired by users, the operating system rejects your request and issues the following message:

     RIN TABLE FULL

In this case you must wait until a global RIN becomes available, or request that your System Manager raise the maximum number of global RINs that MPE XL can assign.

For additional information about the :GETRIN command, refer to the MPE XL Commands Reference Manual (32650-90003).

Locking and Unlocking Global RINs

Your process can lock a global RIN using the LOCKGLORIN intrinsic. Once you have successfully locked the RIN, no other process can lock the same global RIN until you either unlock it with the UNLOCKGLORIN intrinsic, or your process terminates.

While you have the global RIN locked, you are guaranteed exclusive access to the resource associated with the global RIN, so long as other processes first attempt to lock the same global RIN, prior to accessing the resource.

Following is an example of a LOCKGLORIN intrinsic call:

          . 

          . 

          . 

     RINNUM := 4; 

     LOCKCOND := 1; 

     RINPASSWORD := 'RIN4LOCK  '; 

     LOCKGLORIN (RINNUM,LOCKCOND,RINPASSWORD); 

          . 

          . 

          .

The parameters specified in the example are described below.

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

You use the UNLOCKGLORIN intrinsic to unlock a global RIN your process has previously locked with LOCKGLORIN. Once your process unlocks the RIN, it is available to be locked by other LOCKGLORIN calls.

Following is an example of an UNLOCKGLORIN intrinsic call:

             . 

             . 

             . 

         RINNUM := 4; 

        UNLOCKGLORIN (RINNUM) 

             . 

             . 

             .

The parameter specified in the above example is described below.

RINNUM Passes the global RIN associated with the resource you no longer wish exclusive access to. To unlock this global RIN, you must have previously locked it using LOCKGLORIN. The value 4 is a global RIN returned by the :GETRIN command.

Appendix A contains a program that uses global RINs to manage access to records in a data file being shared among multiple readers/writers. The program can be considered to be part of a book record maintenance application used in a library. Specifically, the program updates the location field of a book record located in the data file.

Consider, also, that the library has several sites where users can check out books. A librarian at each site has a terminal logged on to a session running the maintenance application. Different sessions, then, must be able to share access to the same data file for the purposes of updating book records.

Anytime a book is checked in or checked out from any site, the data file is updated to reflect the new location of the book. For example, if a book is checked in, the librarian who receives the book must update the record associated with the book, changing the location from LOANED CARD# 451, DUE APRIL 1 to AVAILABLE so that the records reflect the current location of the book.

A problem exists maintaining the integrity of the records when two or more librarians access the same record simultaneously. For example, if two librarians, "A" and "B", access a book record simultaneously, the following may occur if provisions are not made to guarantee exclusive access to a record during updates:

"A" copies the book record into her stack, showing the book is available.
"B" simultaneously copies the same record into his stack, showing the book is available. This can occur because the data file is opened with the access type option of HPFOPEN/FOPEN set to SHARE (any other process, in any other session, can concurrently access this file).
"A" updates the location field of the record showing the book to be checked out, then posts the record to disc.
"B" updates the location field of the record showing a 24-hour hold on the book, then posts the record to disc.

The final result of this sequence is "B" overwriting the updated location entered by "A". The true location of the book has been lost. What should have occurred is that "B" should not have been able to access the record for the purposes of updating until "A" was finished with the update process.

Appendix A shows a program using the LOCKGLORIN and UNLOCKGLORIN intrinsics to ensure exclusive access to book records during an update. The program allows a user to lock four records in a file so that a record can be updated without chance of another user updating it simultaneously. In the program, the other users are not suspended when attempting to access records elsewhere in the file.

The file BOOKFILE, illustrated in Example 2-1, contains the titles and status of the 20 books in a library. The program in Appendix A uses this file as its data file.

Figure 2-1 FIGURE 2-1

TITLE: THE BORROWERS                FACULTY LOAN - DR. JOHNSON 

TITLE: ALICE IN WONDERLAND          FACULTY LOAN - DR. JOHNSON 

TITLE: PETER PAN                    AVAILABLE 

TITLE: JUNGLE BOOK                  AVAILABLE 

TITLE: THE LIFE OF MERENB           AVAILABLE 

TITLE: INTRO TO TAI CHI CHUAN       AVAILABLE 

TITLE: TOM SAWYER                   LOANED CARD# 275, DUE APRIL 16 

TITLE: TREASURE ISLAND              INTERLIBRARY LOAN - COUNTY LIBRARY 

TITLE: A CHRISTMAS CAROL            AVAILABLE 

TITLE: THE WIZARD OF OZ             AVAILABLE 

TITLE: THE DARK CRYSTAL             AVAILABLE 

TITLE: SPEED RACER                  LOANED CARD# 921, DUE MARCH 25 

TITLE: ULTRAMAN GOES TO TOWN        AVAILABLE 

TITLE: H.M.S. PINAFORE              AVAILABLE 

TITLE: FEAR OF FLYING               FACULTY LOAN - DR. STRANGELOVE 

TITLE: SNOW WHITE                   FACULTY LOAN - DR. CHARMING 

TITLE: DR. DOOLITTLE                INTERLIBRARY LOAN - ACME UNIV. 

TITLE: TALES OF MOTHER GOOSE        AVAILABLE 

TITLE: AESOP'S FABLES               AVAILABLE 

TITLE: THE GULAG ARCHIPELAGO        LOANED CARD #36, DUE MAY 11

Example 2-1. BOOKFILE Contents. BOOKFILE contains 20 records, so the program must acquire five global RINs. (The program uses four records per global RIN). This is accomplished by repeatedly issuing the command:

     :GETRIN BOOKRIN

BOOKRIN is the rinpassword specified in the program to lock the global RIN. Because MPE XL does not always assign global RINs in sequence, and because the program requires consecutive RINs to keep track of them more easily, it may be necessary to enter more :GETRIN commands before the program is first run in order to acquire the five consecutive global RINs. Extra RINs can be released with the :FREERIN command. For the purposes of this example, we assume that RINs 1 through 5 have been assigned.

The program in Appendix A uses the following procedures to accomplish its task:

Procedure error_ handler is a standard error handling routine that is invoked whenever an intrinsic call is unsuccessful.
Procedure initialize_variables initializes appropriate global variables prior to use.
Procedure open_files opens the three files required by the program: $STDIN, $STDLIST, and BOOKFILE.
Procedure update_book_information is the main procedure called after files have been opened. This procedure prints the program header to $STDLIST, then repeatedly prompts the user for a record to update (procedure select_record), until the user presses Return, instead of a record number, to indicate the end of the program. Each time a record is selected, the associated RIN is computed, then procedure access_record_exclusively is called.
Procedure access_record_exclusively (Example 2-2) locks the global RIN associated with the selected record before calling procedure update_record to update the selected record. When procedure update_record is finished, the global RIN is unlocked before the program prompts the users for the next record number.
Procedure update_record prints the selected record to $STDLIST, prompts the user for a new location, then reads the input from $STDIN. If the user supplies a new location, the record is updated, then immediately posted to disc

Figure 2-2 Figure 2-2.

  procedure access_record_exclusively(rinnum:shortint); 

    begin 

    lockglorin(rinnum,lockflag,rinpassword);  {Lock global RIN          } 

    if ccode <> CCE then error_handler(-1,103); 

    freaddir(booklist,bookrecord,-72,accno);  {Read selected bookrecord } 

    if ccode = CCL then error_handler(booklist,104) else 

    if ccode = CCE then update_record;    {Call PROCEDURE update_record } 

    unlockglorin(rinnum);                 {Unlock global RIN            } 

    if ccode <> CCE then error_handler(-1, 110); 

    end;

Example 2-2. Procedure Access_Record_Exclusively. Once the user selects a valid book record, and the correct RIN is computed, the program calls the intrinsic LOCKGLORIN to lock the RIN. If the RIN is already locked (by another process executing the same code to update a record), the record cannot be accessed until the RIN is unlocked by the process that first locked it.

Example 2-3 is a sample of an interactive session with the record update program located in Appendix A. Updated entries are accessed a second time to confirm successful modification.

Figure 2-3 Figure 2-3



:RUN BKUPDATE 



LIBRARY INFORMATION PROGRAM. 

ACCESSION NO:  4 

TITLE:  THE LIFE OF MERENB        INTERLIBRARY LOAN - UNIV. OF OZ 

NEW LOCATION  AVAILABLE 

ACCESSION NO:  4 

TITLE: THE LIFE OF MERENB         AVAILABLE 

NEW LOCATION  Return 

ACCESSION NO:  1 

TITLE:  ALICE IN WONDERLAND       LOANED CARD# 451, DUE APRIL 1 

NEW LOCATION  FACULTYLOAN-DR.JOHNSON 

ACCESSION NO:  1 

TITLE: ALICE IN WONDERLAND        FACULTY LOAN - DR. JOHNSON 

NEW LOCATION  Return 

ACCESSION NO:  18 

TITLE: AESOP'S FABLES             AVAILABLE 

NEW LOCATION  Return 

ACCESSION NO:  Return 



END OF PROGRAM 

:

Example 2-3.  Execution of Record Update Program.

Releasing Global RINs

If you are the owner of a global RIN, you can use the :FREERIN command to release the global RIN back to the pool of free global RINs maintained by the operating system.

Following is an example of a :FREERIN call:

     :FREERIN 8

where 8 is the global RIN you want released.




	NOTE: You should be certain that all other users of a global RIN are finished using the RIN before you release it back to MPE XL.

For additional information about the :FREERIN command, refer to the MPE XL Commands Reference Manual (32650- 90003).

Managing with Global RINs

Technical documentation

» Table of Contents

» Index

Acquiring Global RINs

Locking and Unlocking Global RINs

Releasing Global RINs