PURPOSE: Six clauses of the RELATE statement control aspects of the Simultaneous Update environments. The FOR clause specifies precisely which operations the PM will perform on the DS. Similarly, the ALLOWING clause specifies precisely which operations other users will be allowed to perform on the DS while this PM controls it. When it specifies one or more of the allowed operations, the ALLOWING clause also activates the Concurrent Queued environment, which causes record-level queuing so that it is possible to get multiple-user update (see description of Concurrent Queued environment earlier in the chapter). When the ALLOWING clause specifies the option OTHERS TO WAIT, it activates the Exclusive Queued environment (see description earlier in this chapter).
The other four clauses described here are all default override clauses, which are used to specify how long a PM should wait for a busy DS or record and to control what is displayed on the screen while the PM waits.
FORM 1: For Master and Transaction
RELATE {DS; SD; DI} name {WITH; TO; AS} {MASTER; TRANSACTION} [FOR
operation] [ALLOWING /OTHERS TO/ {WAIT; operation}] [default override clauses]
FORM 2: For Auxiliary DS’s or DI’s
RELATE {DS; SD; DI} name {WITH; TO ; AS} designator [ON \\field\\] [FOR operation]
[default override clauses] [ALLOWING /OTHERS TO/ {WAIT; operation}]
{DS; SD; DI} name, {WITH; TO; AS}, {MASTER; TRANSACTION}, designator, and ON \\field\\ are as discussed in the primary discussion of RELATE, in chapter 13.
The ON \\field\\ option cannot be used when an ALLOWING clause establishes the Concurrent Queued environment for the DS.
FOR operation specifies the operations that this PM will perform on the related DS. The operations are:
GET (or INPUT)
GET PUT
GET DELETE
GET PUT DELETE
APPEND
GET PUT APPEND
GET DELETE APPEND
UPDATE (or GET PUT DELETE APPEND)
CREATE
Notice that the operations given in the FOR clause correspond to the statements that will be used later in the PM to manipulate records in the related DS. The operations must be listed in the FOR clause in the order shown above.
GET (or INPUT) declares the DS for reading (input) only.
GET PUT declares the DS for reading and changing records.
GET DELETE declares the DS for reading and deleting records.
GET PUT DELETE declares the DS for reading, changing, and deleting records.
APPEND declares the DS for accepting newly created records that are appended to existing records in the DS.
GET PUT APPEND declares the DS for reading, changing, and appending new records.
GET DELETE APPEND declares the DS for reading, deleting, and appending newly created records.
UPDATE (or GET PUT DELETE APPEND) declares the DS for reading, deleting, changing and appending new records. UPDATE is synonymous with GET PUT DELETE APPEND.
CREATE declares the DS for accepting newly created records. Unlike the other operations that can be specified in the FOR clause, this one may not be used with an ALLOWING clause. The DS will be cleared of all records before new records are written. In other words, when a DS is related FOR CREATE, it will be superseded, and the request for access cannot be queued. The program must wait until all queued users release the DS. While the DS is opened for CREATE, it is not accessible to others (except those wanting input access in a default environment).
ALLOWING clause specifies what other types of jobs may access the DS while it is used by the PM. For example, if a DS is related with ALLOWING GET, only those jobs immediately following it in the queue that request GET can access the DS concurrently. Others must wait in the queue for their turn. When the ALLOWING clause specifies any operation, it establishes both DS access and record access.
The ALLOWING clause is optional. When there is no ALLOWING clause, the access environment uses the default environment.
ALLOWING OTHERS TO WAIT specifies exclusive access to the DS. This clause sets up the Exclusive Queued environment. This PM will only get access to the DS when all previous users in the queue have released the DS, and during the execution of this PM, no succeeding user may concurrently access the same DS.
ALLOWING OTHERS TO operation activates the Concurrent Queued environment; that is, it established record-level queuing, as well as DS level queuing (see description of Concurrent Queued environment earlier in this section). Any operation allowed in the FOR clause can be used here except CREATE.
The most useful combinations of FOR and ALLOWING clauses are listed below. Each entry in the list also shows which environment is created by the given ALLOWING clause.
|
FOR |
ALLOWING |
Environment |
Record Queued |
|
GET |
UPDATE |
Concurrent Queued |
Yes |
|
GET |
GET |
Concurrent Queued |
Yes |
|
UPDATE |
GET |
Concurrent Queued |
Yes |
|
UPDATE |
UPDATE |
Concurrent Queued |
Yes |
|
GET |
WAIT |
Exclusive Queued |
No |
|
UPDATE |
WAIT |
Exclusive Queued |
No |
|
CREATE |
--- |
Default - no DS queue |
No |
Default override clauses are used to change the default environment during data accessing. They are only valid when an ALLOWING clause is specified. The default override clauses are:
[DS /WAIT/ MESSAGE /IS/ {DISABLES; ENABLED}]
[RECORD /WAIT/ MESSAGE /IS/ {DISABLED; ENABLED}]
[WAIT {n /SECONDS/; FOREVER} /FOR/ DS]
[WAIT {n /SECONDS/; FOREVER} /FOR/ RECORD]
[DS /WAIT/ MESSAGE /IS/ {DISABLES; ENABLED}] is used to control the printing of a message whenever ACCENT R waits for a busy DS. The message is stored in the system field @DS.MESSAGE and is printed every 30 seconds until access is granted or until @DS.WAIT seconds has elapsed. The default message is “Waiting for {N} in use by job {I} user {S},” where N is the DS name, I is the job number currently using the DS and S is the name of that user. (If more than one user has access, the one named is chosen at random.) The message may be changed by changing the system field @DS.MESSAGE.
[RECORD /WAIT/ MESSAGE /IS/ {DISABLED; ENABLED}] is used to control the printing of a message whenever ACCENT R waits for a busy record. The message is stored in the system field @RECORD.MESSAGE and is printed every 30 seconds until access is granted or until @RECORD.WAIT seconds elapse. The default message is “Waiting for record in (N) in use by job (I) user (S)”, where N, I, S are as described above. The message may be changed by modifying the SF @RECORD.MESSAGE.
[WAIT {n /SECONDS/; FOREVER} /FOR/ DS] specifies the maximum number of seconds to wait for a queued DS. This clause overrides the value stored in the system field @DS.WAIT; the default is 300 seconds. The job aborts when the wait period exceeds @DS.WAIT seconds or the value given here.
[WAIT {n /SECONDS/; FOREVER} /FOR/ RECORD] specifies the maximum number of seconds to wait for a busy record. This clause overrides the value stored in the system field @RECORDS.WAIT; the default is 300 seconds. When the waiting period exceeds @RECORD.WAIT seconds or the value specified here, the system field @AUX is set to “BUSY”, the executing statement fails, and the PM continues.
NOTES: The DEFER OPEN option of the RELATE statement is not allowed when any queued environment is in effect for the DS. The system field @DS.MESSAGE, @DS.WAIT, @RECORD.MESSAGE, and @RECORD.WAIT are all described in detail later in this chapter.
This example illustrates data accessing with users specifying different combination of FOR clause and ALLOWING clause in the RELATE statement. All jobs below have requested access to the same DS. The STATUS columns are time sequenced from left to right.
| Job | Relate For | Allowing Others To |
Job Sequence: Time Sequence | ||||
|
Status (1) |
Status (2) |
Status (3) |
Status (4) |
Status (5) |
|||
| 1 | UPDATE | GET PUT | running | done | ··· | ··· | ··· |
| 2 | GET | UPDATE | running | done | ··· | ··· | ··· |
| 3 | GET PUT | UPDATE | running | done | ··· | ··· | ··· |
| 4 | GET | WAIT | queued | running | done | ··· | ··· |
| 5 | UPDATE | UPDATE | queued | queued | running | done | ··· |
| 6 | UPDATE | UPDATE | queued | queued | running | done | ··· |
| 7 | UPDATE | GET PUT | queued | queued | queued | running | done |
| 8 | UPDATE | GET | queued | queued | queued | queued | running |
| 9 | GET PUT | UPDATE | queued | queued | queued | queued | queued |
Jobs 1, 2, and 3 run concurrently since their FOR clauses and ALLOWING clauses permit each other to concurrently access the DS. Note that UPDATE is equivalent to GET DELETE PUT APPEND.
Job 4 runs by itself, since an ALLOWING OTHERS TO WAIT clause specifies exclusive access to the DS; i.e., it establishes the Exclusive Queued environment.
Jobs 5 and 6 both create the Concurrent Queued environment, and both allow others to update, so they can run together.
Jobs 7 and 9 are compatible, but because 8 is not compatible and cannot run with 7, 9 must wait. No job is ever allowed to move up in front of an earlier job in the queue; such a practice might lead to indefinite postponement, as job after job jumps in front of an incompatible one.