Undo log associations

You can use the Undo logs assignment feature to set up multiple undo logs, which are associated with particular user IDs, job name prefixes, or high-level qualifiers of VSAM sphere names. When you submit a VSAM sphere update job that involves undo logging, CICS® VR searches for any matching associations.

When CICS VR finds an association that applies to a submitted job, it writes undo records to the undo log named for the association. If no association is found for the job, records are written to the default undo log that is defined for the system. Only one undo log can be used for each job.

When you select option 1, Undo logs assignment, on the CICS VR settings panel, option 8 from the CICS VR main menu, the CICS VR Undo logs assignment panel is displayed. This panel lists all the associations that are currently in effect.

Figure 1. CICS VR Undo logs assignment panel

Administrate  View  Help                                                 
------------------------------------------------------------------------------ 
DWWPPULA                 CICSVR Undo logs assignment           Row 1 to 8 of 8 
                                                                               
Select one or more associations, then select an action. Or, use Add action to  
register new association.
                                                                               
                                                                               
  S  Value     Type      Undo log name               Time (GMT)                
  _  CICSMVS7  HLQ       CM7.UNDOLOG                 08.181 15:13:12           
  _  CICSVR2   HLQ       TEST.TST2.UNDOLOG           08.181 15:13:17           
  _  AT*       JOBNAME   DWW.USER.UNDOLOG            08.185 16:11:08           
  _  ATEST2*   JOBNAME   TEST.TST2.UNDOLOG           08.181 15:14:05           
  _  ATEST1    JOBNAME   TEST.TST1.UNDOLOG           08.179 16:01:43           
  _  AAAA      USERID    DWW.USER.UNDOLOG            08.185 15:35:24           
  _  APROD*    JOBNAME   PROD.UNDOLOG                06.184 13:17:31           
  _  TESTUSER  USERID    TEST.TST1.UNDOLOG           06.184 13:17:31           

  
                                                                              
Command ===>                                                                   
  F1=Help      F3=Exit     F4=SwSort    F5=Add       F6=Alter       F7=Bkwd
  F8=Fwd      F10=Menu bar F11=Delete   F12=Cancel

The list shows the following information about each association:

Value

The string that CICS VR tries to match when searching for any association that applies to a submitted job.

Type

The type of association; so whether the value string is a user ID, a job name prefix, or the high-level qualifier for a VSAM sphere name:

USERID: The value for this association is the user ID under which the job runs. With this association in effect, for every VSAM sphere update job submitted by this user, undo records are written to the named undo log. The value is the exact user ID.
JOBNAME: The value for this association is the job name prefix of the VSAM sphere update job. With this association in effect, for every VSAM sphere update job with a prefix that matches the stated value, undo records are written to the named undo log. The value can be an exact job name prefix or it can be a mask ending with an asterisk (*) as a wildcard. For example, the association shown in the sample listing with a value of ATEST1 matches only with the job name prefix ATEST1, but the association with a value of ATEST2* matches with any of the job name prefixes ATEST2, ATEST2MON, or ATEST23.
HLQ: The value for this association is the high-level qualifier (HLQ) of a VSAM sphere name. With this association in effect, for every VSAM sphere update job that updates a VSAM sphere with the specified high-level qualifier, undo records are written to the named undo log. The value is the exact high-level qualifier.

Undo log name

The undo log that is used if this association applies to a job. The name of the undo log consists of a prefix, which can be up to 18 characters, followed by .UNDOLOG.

Time

The time when the association was last updated.

You can sort the list of associations by association value, association type, or undo log name. To sort the list, press F4, SwSort, to loop through the different sorting types. Each time you press F4, the list is repopulated based on the new sorting type.

Matching rules for associations

CICS VR must find only one matching association to select the correct undo log for a particular VSAM sphere update job. You do not have to define all the types of association for each job. For example, if CICS VR finds a user ID association for a particular job, it can select the correct undo log on this basis, and does not need to find a job name prefix association and high-level qualifier association as well.

However, because you can define different types of association, some VSAM sphere update jobs that you submit might match the value for more than one association. For example, a job might be submitted with the job name prefix ATEST2, to update a VSAM sphere with a name that has the high-level qualifier CICSVR2. This job matches more than one association in the sample listing. Because only one undo log can be used for each job, CICS VR applies some matching rules to make sure that it has selected the undo log that you intended for the job:

The user ID associations are searched first, followed by the job name prefix associations, followed by the high-level qualifier associations.
If a match is found with an association of one type, CICS VR continues searching all the remaining association types, to check that no conflicting associations of other types occur. If another matching association is found that names a different undo log, CICS VR undo logging produces an error and does not start. For example, if a job is submitted with the job name prefix ATEST2 to update a VSAM sphere with a name that has the high-level qualifier CICSVR2, CICS VR finds a matching association for both the job name prefix and the high-level qualifier. Because these associations both name the undo log TEST.TST2.UNDOLOG, they do not conflict, and the undo logging can proceed. However, if the same job is submitted with the job name prefix ATEST1, a matching job name prefix association exists that names the undo log TEST.TST1.UNDOLOG, followed by a matching high-level qualifier association that names the undo log TEST.TST2.UNDOLOG. In this case, you have a conflict, and the undo logging cannot proceed.
For job name prefix associations, if you have set up associations using masks, and a job name prefix therefore matches the value of more than one association, CICS VR selects the association with the fullest match. For example, the sample listing includes job name prefix associations with values of AT*, ATEST2*, and ATEST1. For a job submitted with the job name prefix ATEST23, CICS VR selects the association with a value of ATEST2*, rather than AT*, because that is the fullest match.
- If you are updating multiple VSAM spheres in the same job, and you have no matching user ID association or job name prefix association, all the VSAM sphere names must have a high-level qualifier association, and these must all point to the same undo log.
- If you have no high-level qualifier associations in effect at all for the VSAM spheres in the job, that is also acceptable. If CICS VR finds that one of the VSAM sphere names has a high-level qualifier association pointing to a different undo log, or that some have matching associations but others do not match any association, CICS VR undo logging produces an error and stops. This error cannot be discovered until processing starts against the first VSAM data set that is different from those encountered previously.
- If a matching user ID association or job name prefix association for the job exists, it is not important if some of the VSAM sphere names do not match any association, but it is important if they have associations pointing to different undo logs, because of a conflict.

If an error occurs, the job proceeds without undo logging.

If no matching associations of any type are found for a job, the undo records are written to the default undo log that is defined for the system. The prefix for the default undo log name is specified in the CICSVR_UNDOLOG_PREFIX(prefix) parameter in the active IGDSMSxx member of SYS1.PARMLIB. The default prefix is DWW, so the default name for the default undo log is DWW.UNDOLOG. You must define the default undo log before you submit any job involving undo logging. The CICS VR undo loggingCICS VR Implementation Guide and Reference explains how to define an undo log.