Lock Enforcement Rules

Resolving The Problem

Allocating Resources

This information is from the OS/400 CL Programming manual, SC41-5721-03, Chapter 4.16.

Objects are allocated on the system to guarantee integrity and to promote the highest possible degree of concurrency. An object is protected even though several operations may be performed on it at the same time. For example, an object is allocated so that two users can read the object at the same time or one user can only read the object while another can read and update the same object.

OS/400 allocates objects by the function being performed on the object. For example:

o	If a user is displaying or dumping an object, another user can read the object.
o	If a user is changing, deleting, renaming, or moving an object, no one else can use the object.
o	If a user is saving an object, someone else can read the object, but not update or delete it; if a user is restoring the object, no one else can read or update the object.
o	If a user is opening a database file for input, another user can read the file. If a user is opening a database file for output, another user can update the file.
o	If a user is opening a device file, another user can only read the file.

Generally, objects are allocated on demand; that is, when a job step needs an object, it allocates the object, uses the object, and deallocates the object so another job can use it. The first job that requests the object is allocated the object. In your program, you can handle the exceptions that occur if an object cannot be allocated by your request. (See Chapter 7 and Chapter 8 for more information on monitoring for messages or your high-level language reference manual for information on handling exceptions.)

Sometimes you want to allocate an object for a job before the job needs the object, to ensure its availability so a function that has only partially completed would not have to wait for an object. This is called preallocating an object. You can preallocate objects using the Allocate Object (ALCOBJ) command.

Objects are allocated on the basis of their intended use (read or update) and whether they can be shared (used by more than one job). The file and member are always allocated *SHRRD and the file data is allocated with the level of lock specified with the lock state. A lock state identifies the use of the object and whether it is shared. The five lock states are (parameter values given in parentheses):

o	Exclusive (*EXCL). The object is reserved for the exclusive use of the requesting job; no other jobs can use the object. However, if the object is already allocated to another job, your job cannot get exclusive use of the object. This lock state is appropriate when a user does not want any other user to have access to the object until the function being performed is complete.
o	Exclusive allow read (*EXCLRD). The object is allocated to the job that requested it, but other jobs can read the object. This lock is appropriate when a user wants to prevent other users from performing any operation other than a read.
o	Shared for update (*SHRUPD). The object can be shared either for update or read with another job. That is, another user can request either a shared-for-read lock state or a shared-for-update lock state for the same object. This lock state is appropriate when a user intends to change an object but wants to allow other users to read or change the same object.
o	Shared no update (*SHRNUP). The object can be shared with another job if the job requests either a shared-no-update lock state, or a shared-for-read lock state. This lock state is appropriate when a user does not intend to change an object but wants to ensure that no other user changes the object.
o	Shared for read (*SHRRD). The object can be shared with another job if the user does not request exclusive use of the object. That is, another user can request an exclusive-allow-read, shared-for-update, shared-for-read, or shared-no-update lock state.

Note: The allocation of a library does not restrict the operations that can be performed on the objects within the library. That is, if one job places an exclusive-allow-read or shared-for-update lock state on a library, other jobs can no longer place objects in or remove objects from the library; however, the other jobs can still update objects within the library.

The following table shows the valid lock state combinations for an object:

Table 4-5. Valid Lock State Combinations
If One Job Obtains This Lock State:	Another Job Can Obtain This Lock State:
*EXCL	None
*EXCLRD	*SHRRD
*SHRUPD	*SHRUPD or *SHRRD
*SHRNUP	*SHRNUP or *SHRRD
*SHRRD	*EXCLRD, *SHRUPD, *SHRNUP, or *SHRRD

You can specify all five lock states (*EXCL, *EXCLRD, SHRUPD, SHRNUP, and SHRRD) for most object types. this does not apply to all object types. Object types that cannot have all five lock states specified are listed in the following table with valid lock states for the object type:

Table 4-6. Valid Lock States for Specific Object Types
Object Type	*EXCL	*EXCLRD	*SHRUPD	*SHRNUP	*SHRRD
Device description		x
Library		x	x	x	x
Message queue	x				x
Panel group	x	x
Program	x	x			x
Subsystem description	x

To allocate an object, you must have object existence authority, object management authority, or operational authority for the object. Allocated objects are automatically deallocated at the end of a routing step. To deallocate an object at any other time, use the Deallocate Object (DLCOBJ) command.

You can allocate a program before it is called to protect it from being deleted. To prevent a program from running in different jobs at the same time, an exclusive lock must be placed on the program in each job before the program is called in any job. The following objects cannot be allocated with the ALCOBJ command:

o	AS/400 IBM Advanced 36 Machine
o	AS/400 Advanced 36 Machine Configuration

You cannot use the ALCOBJ or DLCOBJ commands to allocate an APPC device description.

The following example is a batch job that needs two files members for updating. Members from either file can be read by another program while being updated, but no other programs can update these members while this job is running. The first member of each file is preallocated with an exclusive-allow-read lock state.

Example

//JOB JOBD(ORDER)
ALCOBJ OBJ((FILEA *FILE *EXCLRD) (FILEB *FILE *EXCLRD))
CALL PROGX
//ENDJOB

Objects that are allocated to you should be deallocated as soon as you are finished using them because other users may need those objects. However, allocated objects are automatically deallocated at the end of the routing step.

If the first members of FILEA and FILEB had not been preallocated, the exclusive-allow-read restriction would not have been in effect. When you are using files, you may want to preallocate them so that you are assured they are not changing while you are using them.

Note: If a single object has been allocated more than once (by more than one allocate command), a single DLCOBJ command will not completely deallocate that object. One deallocate command is required for each allocate command.

It is not an error if the DLCOBJ command is issued against an object where you do not have a lock or do not have the specific lock state requested to be allocated.

You can change the lock state of an object, as the following example shows:

PGM
ALCOBJ OBJ((FILEX *FILE *EXCL)) WAIT(0)
CALL PGMA
ALCOBJ OBJ((FILEX *FILE *EXCLRD))
DLCOBJ OBJ((FILEX *FILE *EXCL))
CALL PGMB
DLCOBJ OBJ((FILEX *FILE *EXCLRD))
ENDPGM
File FILEX is allocated exclusively for PGMA, but FILEX is allocated as exclusive-allow-read for PGMB.

You can use record locks to allocate data records within a file. You can also use the WAITFILE parameter on a Create File command to specify how long your program is to wait for that file before a time-out occurs.

The WAITRCD parameter on a Create File command specifies how long to wait for a record lock. The DFTWAIT parameter on the Create Class (CRTCLS) command specifies how long to wait for other objects. For a discussion of the WAITRCD parameter, see the Backup and Recovery manual.