Variables, Substitution, and Assignment › Vartable Facility › Shared Table Updating

Shared Table Updating

Tables allocated with a scope of REGION or SYSTEM can be accessed by any number of concurrently running NCL procedures. An NCL procedure can be interrupted at any time and another procedure can be scheduled. If two procedures are manipulating the same table, the possibility of logical corruption exists.

Example: Shared Table Updating

In this example, assume that the entry with key KEY001 has a data content of 10 before the code is executed.

procedure 1 procedure 2

&K = KEY001
&VARTABLE GET ID=T1 +
            SCOPE=SYSTEM +
            KEY=K FIELDS=D VARS=DATA
&D = &D + 1  -* &D now 11
-*
-* system interrupts procedure 1, schedules procedure 2
-*

                     &K = KEY001
                     &VARTABLE GET ID=T1 +
                                 SCOPE=SYSTEM +
                                 KEY=K FIELDS=D VARS=DATA
                     &D = &D + 1  -* &D now 11
                     &VARTABLE PUT ID=T1 +
                                 SCOPE=SYSTEM +
                                 KEY=K FIELDS=D VARS=DATA
                     &END
-*
-* system re-schedules procedure 1
-*
&VARTABLE PUT ID=T1 +
            SCOPE=SYSTEM +
            KEY=K FIELDS=D VARS=DATA

If the data in the table entry was being used as a counter, instead of having 12 (because of 2 adds), it only has 11, as the update done by procedure 2 is lost.

There are three solutions to the problem:

• If a single counter is being maintained in each entry, there is no need to get, alter, then update the table entries. Instead, you can use the ADJUST= or FIELDS=(ADJUST) options of the &VARTABLE PUT, UPDATE, or ADD operands to change the system-maintained counter fields in the entry without interference from any other procedure that is using the table. The previous example could be written as:

  &K = KEY001
  &VARTABLE PUT ID=T1 SCOPE=SYSTEM +
  

             KEY=K ADJUST=1
  

  This would insert a new entry if it did not already exist, and add 1 to the (zeroed) counter, or update an existing entry by adding 1 to the current counter value.

  This approach is extremely useful for event counting, where the event (for example, a particular message ID) is described by the key.

• Use the &LOCK verb to lock the key value during the manipulation:

  &LOCK TYPE=EXCL .....  use key as resource name....
  &VARTABLE GET ...
  ...  manipulate the table entry
  &VARTABLE UPDATE ...
  &LOCK TYPE=FREE ..... 
  

  The &LOCK verb is described in the Network Control Language Reference Guide.

  This approach allows almost any manipulation to take place. However, for heavily accessed tables, the overheads of LOCK/UNLOCK could be excessive. If you do not know the key of an entry in advance, you might need to lock the entire table.

• If we assume that minimal contention for any one table entry, a third approach is to consider we can access it and only redo our work if someone else actually changes the entry while we are performing calculations.

  Remember that each entry in a vartable contains a user correlator. This is a system-maintained update counter. An &VARTABLE GET operation can request that the current value of the correlator for the requested entry be returned in a nominated variable. The actual format of the correlator is of no consequence, and should not be altered by the procedure.

  When the procedure issues the &VARTABLE UPDATE, &VARTABLE PUT, or &VARTABLE DELETE, the name of the variable containing the correlator should be supplied in the VARS list (and .USERCORR specified in the FIELDS list). The system checks that the correlator matches the current value of the correlator in the current table entry, and only if they are the same, performs the update or delete operation (if PUT, and the entry is new, the correlator is ignored).

  Following the update, the correlator in the table entry is given a new, unique value (again, of no consequence to the procedure).

  Obviously, if two procedures issue a GET for the same entry, with no intervening updates to that entry, they will both be given the same correlator value. But, if both then attempt to update that entry, supplying the same correlator value, the second update will fail (with &ZFDBK set to 8), and it should reissue the GET, and redo the update logic.

Example: Shared Table

&K = KEY001
.RETRY     -* loop here if update fails on correlator
           -* mismatch

&VARTABLE GET ID=T1 SCOPE=SYSTEM KEY=K +
        FIELDS=(.DATA,.USERCORR) VARS=(D,UC)
           -*
           -* manipulate the entry data (in &D).
           -*
&VARTABLE PUT ID=T1 SCOPE=SYSTEM KEY=K +
        FIELDS=(.DATA,.USERCORR) VARS=(D,UC)

&IF &ZFDBK = 8 &THEN &GOTO .RETRY-* loop if
                                 -* changed

Note: Because no locks are held, there is no extra work to release those locks should the procedure encounter an error condition while manipulating the data.

Also, if the GET is using an OPT= that retrieves a different key value record (for example OPT=GEN), you do not need to know in advance what key value to lock. If &LOCK had to be used in this case, you might need to lock the entire table.

Note: The use of the user correlator can be forced, for a particular table, by specifying USERCORR=YES when allocating it.

(To contrast these two views, (2) can be regarded as the conservative approach, and (3) can be regarded as the aggressive approach.)