Resource Management Programmer's Guide 900 Series HP 3000 Computers ABCDE HP Part No. 32650-90024 Printed in U.S.A.
The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability or tness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material.
Printing History The following table lists the printings of this document, together with the respective release dates for each edition. The software version indicates the version of the software product at the time this document was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions. Edition Date Software Version First Edition November 1987 A.01.
Documentation Map iv
v
Preface Resource Management Programmer's Guide (32650-90024) is written for an experienced programmer who has a working knowledge of MPE/iX and is familiar with: A text editor At least one programming language Compiling, linking, and executing a program on MPE/iX This manual contains detailed instructions describing how you can use system intrinsics within your application to accomplish two resource management tasks available through MPE/iX: Managing Shared Resources with Resource Identi cation Numbers (R
Conventions NOTATION UPPERCASE DESCRIPTION Within syntax statements, characters in uppercase must be entered in exactly the order shown, though you can enter them in either uppercase or lowercase. For example: SHOWJOB Valid entries: showjob italics { } ] lename Within syntax statements, punctuation characters (other than brackets, braces, vertical parallel lines, and ellipses) must be entered exactly as shown. Within syntax statements, braces enclose required elements.
NOTATION [ ... ] DESCRIPTION Within syntax statements, a horizontal ellipsis enclosed in brackets indicates that you can repeatedly select elements that appear within the immediately preceding pair of brackets or braces. In the following example, you can select itemname and its delimiter zero or more times. Each instance of itemname must be preceded by a comma: [,itemname][ . . . ] If a punctuation character precedes the ellipsis, you must use that character as a delimiter to separate repeated elements.
NOTATION 4 The symbol 4 5 indicates a key on the terminal's keyboard. For example, 4CTRL5 indicates the Control key. 4CTRL5 char indicates a control character. For example, 4CTRL5 Y means you have to simultaneously press the Control key and the Y key on the keyboard. The pre xes %, #, and $ specify the numerical base of the value that follows: 5 4CTRL5 DESCRIPTION char base pre xes %num speci es an octal number. #num speci es a decimal number. $num speci es a hexadecimal number.
Contents 1. Introduction Managing Shared Resources with RINs . . . . . . . . . . . . . . . . . Dynamic Loading of Library Procedures . . . . . . . . . . . . . . . . . 2. Managing Shared Resources with RINs Multiple RIN (MR) Capability . . . . Managing with Global RINs . . . . . Acquiring Global RINs . . . . . . Locking and Unlocking Global RINs . Releasing Global RINs . . . . . . . Managing with Local RINs . . . . . . Acquiring Local RINs . . . . . . . Locking and Unlocking Local RINs .
Figures 2-1. 2-2. 2-3. 2-4. 2-5. 2-6. 3-1. 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Illustration of a Load Time Binding Sequence. Illustration of Run Time Binding of an XL. . Contents-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 Introduction Any element of an HP 3000 computer system that your program can access through MPE XL can be considered a resource. A resource can be an input or output device, a le, a subroutine, a library procedure, or a private data area. A major function of MPE XL is to manage resources in such a way as to make your programming e orts easier and more e cient. MPE XL also provides you with system intrinsics to accomplish various tasks related to managing the resources your program may access.
Dynamic Loading of Library Procedures Chapter 3 describes how you can dynamically bind and load a procedure located in an executable library (XL). This chapter discusses the following system intrinsics: HPGETPROCPLABEL intrinsic HPFIRSTLIBRARY intrinsic HPMYFILE intrinsic HPMYPROGRAM intrinsic Appendix B contains a program example illustrating the use of the HPGETPROCPLABEL intrinsic.
2 Managing Shared Resources with RINs When you are developing an application you may wish to manage a speci c resource that is being shared by a set of processes in a way that guarantees that one process at a time has exclusive access to that resource. MPE XL provides Resource Identi cation Numbers (RINs) that enable you to manage shared resources.
Multiple RIN (MR) Capability There are two types of RIN available for your use: Global RIN, used to manage a resource shared by processes located in di erent jobs/sessions. Local RIN, used to manage a resource shared by processes located in the same job/session. If you have standard user capabilities you can lock more than one local RIN at the same time. However, you can lock only one global RIN at a time, because of the danger of a system deadlock resulting from the improper use of global RINs.
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.
LOCKGLORIN (RINNUM,LOCKCOND,RINPASSWORD); . . . The parameters speci ed 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: RINPASSWORD RINPASSWORD passes the RIN password assigned to the global RIN through the :GETRIN command.
The parameter speci ed 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 le being shared among multiple readers/writers.
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 le 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 le. The le BOOKFILE, illustrated in Example 2-1, contains the titles and status of the 20 books in a library.
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 les required by the program: $STDIN, $STDLIST, and BOOKFILE. Procedure update_book_information is the main procedure called after les have been opened.
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 con rm successful modi cation. :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 4Return5 ACCESSION NO: 1 TITLE: ALICE IN WONDERLAND LOANED CARD# 451, DUE APRIL 1 NEW LOCATION FACULTYLOAN-DR.
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.
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.
PARENT PROCESS CHILD PROCESS { PARENT BEGINS EXECUTION } . . . HPFOPEN (LP,STATUS,...); GETLOCRIN (3); LPRIN := 1; FWRITE (LP,...); CREATE (PROGNAME,,CHILD...); LOCKLOCRIN (LPRIN,1); ACTIVATE (CHILD); FWRITE (LP,...); . . . . . . . . . . . UNLOCKLOCRIN (LPRIN); . LOCKLOCRIN (LPRIN,1); { CHILD BEGINS EXECUTION } . . 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. . . .
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 rst accesses LP, CHILD has not been created, and so RIN management is not yet required. To guarantee exclusive access to LP rst, PARENT locks LPRIN before CHILD is activated. When PARENT nishes with LP, it unlocks LPRIN, thus making LPRIN available to be locked.
PARENT PROCESS CHILD PROCESS { PARENT EXECUTING } . GETLOCRIN (2); . CHILDCOUNT := 0; WHILE CHILDCOUNT <= MAXCOUNT DO BEGIN SUSPEND (CHILDWAIT,SYNCHRIN); { PARENT IS SUSPENDED UNTIL ACTIVATED BY A CHILD . LOCKLOCRIN (SYNCHRIN,1); OWNER := LOCRINOWNER (WHICHCHILD); . . CHILDCOUNT := CHILDCOUNT + 1; ACTIVATE (OWNER); END; {WHILE LOOP} . . . CHILD EXECUTING } . . LOCKLOCRIN (WHICHCHILD,1); LOCKLOCRIN (SYNCHRIN,1); . . . . . . .
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.
{ PROCESS A EXECUTING . . . LOCKGLORIN (1); LOCKGLORIN (2); PROCESS A REMAINS BLOCKED UNTIL RIN 2 IS UNLOCKED BY PROCESS B. PROCESS A CANNOT UNLOCK RIN 1 WHILE BEING BLOCKED } { PROCESS B EXECUTING . . . LOCKGLORIN (2); LOCKGLORIN (1); } PROCESS B REMAINS BLOCKED UNTIL RIN 1 IS UNLOCKED BY PROCESS A. PROCESS B CANNOT UNLOCK RIN 2 WHILE BEING BLOCKED Figure 2-6. Example 2-6. Deadlock.
In Example 2-6, Process A successfully locks global RIN 1, then attempts to lock global RIN 2 (already locked by Process B). Process A is blocked until it can successfully lock global RIN 2. While Process A is blocked, it cannot unlock global RIN 1, thus making global RIN 1 unavailable for locking by Process B. Process B, meanwhile, has locked global RIN 2 and has been blocked attempting to lock global RIN 1 (locked, or course, by Process A). Global RIN 2 remains unavailable to Process A.
3 Dynamic Loading of Library Procedures Externally referenced procedures located in executable library les (XLs) are normally bound to your program when it is rst loaded at process creation (load time). MPE XL enables you to bind and load a speci ed XL procedure any time during process execution (run time), a feature referred to as dynamic loading.
Bits (16:16) The signed integer value represented by these bits de nes the subsystem that set the status information in Bits (0:16). The NM loader identi cation number is 104. When the value represented by these bits is zero, a normal status is indicated. Determining the Binding Sequence The binding sequence is a list of XLs the loader searches to satisfy your program's unresolved external references. The loader creates the binding sequence at load time.
(Refer to the HP Link Editor/XL Reference Manual (32650-90030) for more information about creating and maintaining XLs.) Searching an Executable Library Not Specified at Load Time HPGETPROCPLABEL can search for procname in one XL not speci ed at load time. The XL must be speci ed in rst le , and any unresolved external references within the XL must be resolved only in the System Libraries.
Note The same procedure name might be repeated in di erent XLs. To ensure that the loader locates the correct procedure, you must be certain that any XLs searched prior to the XL containing the correct procedure do not contain a di erent procedure with the same name. For example, let us assume that the binding sequence in Figure 3-1 is that of your process executing PROGRAM1.
Using HPMYPROGRAM The HPMYPROGRAM intrinsic returns the fully quali ed le name of the program being executed by the calling process (the rst le in the binding sequence). You can pass this name to HPGETPROCPLABEL in the rst le parameter. Using Figure 3-1 as the binding sequence for your program, the following call: HPMYPROGRAM (PROGNAME); returns the fully quali ed le name of your program le, PROGRAM1.GROUP.ACCOUNT.
A Global RIN Program Example This HP Pascal/XL program illustrates how you can use the two intrinsics, LOCKGLORIN and UNLOCKGLORIN, to prevent simultaneous access to a selected record in a shared le while one user is updating the record. Five global RINs were previously acquired through the :GETRIN command. Each RIN is associated with a subset of 4 records in a 20 record data le. This method of assigning RINs allows other users to concurrently access other subsets of records in the same le.
infile,outfile,datafile, {File names used with HPFOPEN } {Required by LOCKGLORIN } rinpassword: packed array [1..
head:= 'LIBRARY INFORMATION PROGRAM '; {Header introduces program change:= 'NEW LOCATION '; {User interface request:= 'ACCESSION NO: '; {User interface end; } } } procedure open_files; {*********************************************************************} { procedure open_files opens all files used by program. } {*********************************************************************} begin hpfopen(stdin,status,2,infile,3,perm,53,ascii); {Open $STDIN } if status.all <> 0 then error_handler(-1, status.
bookrecord.location:= buffer; {Update location field fwritedir(booklist,bookrecord,-72,accno); {Update datafile if ccode <> CCE then error_handler(booklist,108); fcontrol(booklist,2,dummy); {Force posting to disc if ccode <> CCE then error_handler (booklist,109); end; end; } } } procedure access_record_exclusively(rinnum:shortint); {*********************************************************************} { procedure access_record_exclusively locks the global rin associated } { with the selected bookrecord.
end; {Loop } end; {*********************************************************************} { MAIN PROGRAM PART } {*********************************************************************} begin initialize_variables; open_files; update_book_information; end.
B Dynamic Loading Program Example This HP Pascal/XL program example illustrates the use of the HPGETPROCPLABEL intrinsic. HPGETPROCPLABEL returns the plabel of the COMMAND intrinsic. The program requests the user to input the name of a CI command. Both the plabel and the CI command are passed to the HP Pascal/XL CALL procedure which calls COMMAND and directs it to execute the user-speci ed CI command.
PROCEDURE terminate; 000 001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 B-2 INTRINSIC; begin Proc_Name := ' COMMAND '; writeln('About to call hpgetprocplabel'); hpgetprocplabel(Proc_Name, plabel, status); if (status.all <> 0) or (ccode <> 2) then begin writeln('status.subsys:', status.subsys); writeln('status.info: ', status.
Index A Acquiring global RINs , 2-3 Acquiring Local RINs , 2-9 Associating RINs with resources , 2-1 Avoiding deadlock Ranking RINs , 2-16 Avoiding deadlock , 2-14 B Binding at run time , 3-3 Binding sequence De ned , 3-2 Determining , 3-2 Example of , 3-2 Retrieving rst XL in the sequence , 3-4 Retrieving the program le name , 3-5 Retrieving the XL le name , 3-5 Searching through , 3-3 Dynamically loading an XL , 3-3 Dynamic loading De ned , 3-1 Of library procedures , 3-1 Program example , B-1 Using HP
FREELOCRIN , 2-12 FUNLOCK , 2-1 HPFIRSTLIBRARY , 3-4 HPGETPROCPLABEL , 3-1 HPMYFILE , 3-5 HPMYPROGRAM , 3-5 LOCKGLORIN , 2-3 LOCKLOCRIN , 2-9, 2-10 LOCRINOWNER , 2-12 UNLOCKGLORIN , 2-4 UNLOCKLOCRIN , 2-10 L Libraries, executable (XLs) , 3-1 LINK command Specifying the XL list , 3-2 LINK command , 3-2 Loading an executable library dynamically , 3-1 Load time , 3-1 Local RINs Acquiring , 2-9 Deadlock considerations , 2-14 Identifying locker , 2-12 Locking , 2-9 Managing , 2-9 Releasing , 2-12 Unlocking , 2-
X XL libraries , 3-1 XL.PUB.
