Implementing DADS Plus for CICS RLS support using GROUPID and PROPAGATE for RLS file BATCH interface requests

Products

• DADS Plus

Issue/Introduction

VSAM record-level sharing (RLS) enables data sharing across multiple systems in a Parallel Sysplex. VSAM RLS is a data set access mode that allows CICS, batch, and non-CICS applications that run in multiple address spaces and multiple z/OS systems to safely access data at the same time.

RLS access does not change the format of the data in these VSAM data sets, and these same data sets are compatible for non-RLS access. At any one point, a data set can be open for non-RLS write access(non-RLS usage) or open for RLS write access(RLS usage). When a file is set to QUIESCED state, that file has been switched to non-RLS usage. When the file is set to UNQUIESCED state, then that file is switched to RLS usage. For a better understanding of RLS and the QUIESCED/UNQUIESCED states, please refer to the appropriate IBM documentation.

VSAM RLS files can be controlled through the DADS Plus for CICS BATCH INTERFACE by using (1) the PROPAGATE capability to dynamically route a request to all regions defined to DADS Plus for CICS as RLS participants (2) the GROUPID parameter which will send any BATCH INTERFACE request to all regions defined as belonging to a single GROUP or (3) targeting specific APPLIDs with whatever request is being done.

Information that will help a client to decide on which technique to use are explored in this Knowledge Document.

For the following recommendations to work, DADS Plus for CICS must be at Service Pack 2 P0507, plus PTF RO10284. It is highly recommended that RO10396 also be applied - this is the 2009 cumulative maintenance which includes (and therefore sups) RO10284.

Please refer to the DADS Plus for CICS documentation for more detailed information on how to use GROUPID and PROPAGATE in the correct fashion. GROUPID and PROPAGATE are mutually exclusive techniques, and cannot be combined for a single request.

Resolution

The BATCH GROUP (GROUPID) provides the ability to define an association between a group of APPLIDs in the batch interface file. It allows the user to submit a batch request to a group of CICS regions simultaneously, without having to know which of the regions are currently running. Therefore, for a VSAM RLS file that is defined to many different CICS regions, a VSAM RLS file can be QUIESCED or UNQUIESCED when any one of the regions is available by submitting a request to the GROUPID. You must specifically state the GROUPID that is targeted when the BATCH INTERFACE REQUEST is submitted. When you define an APPLID on the DADS Plus for CICS CONTROL FILE, you can also specify a GROUPID the APPLID belongs to. Every APPLID can belong to one and only one GROUPID. A BATCH INTERFACE REQUEST for a GROUPID will internally create multiple BATCH INTERFACE REQUESTS on the DADS Plus for CICS BATCH INTERFACE FILE (BIF), one for every APPLID that belongs to the GROUPID.

PROPAGATION is a method of automatically recognizing that an RLS file is being processed by the BATCH INTERFACE, and then dynamically sending that same request to other regions. To accomplish this, DADS Plus for CICS will send (PROPAGATE) requests for VSAM RLS files to every CICS region that is defined to DADS Plus for CICS as an RLS participant by the DADSGRF SYSID record. For every region that you would like to define as a target for RLS PROPAGATION, you must create an entry in the SYSID record on the DADSGRF file (see below). When DADS Plus for CICS processes a request for a file, and that file is RLS, then PROPAGATION of this request will be done to all entries in the SYSID record on the DADSGRF unless OPTION=N is specified on the BATCH INTERFACE REQUEST.

When PROPAGATION is used, then the DADS Plus for CICS GLOBAL RESOURCE FILE (DADSGRF) is used to serialize requests for VSAM RLS files. It also contains the SYSIDs to which requests for VSAM RLS files will be PROPAGATED. This file must be shared among the CICS regions that access the VSAM RLS files that will be controlled by PROPAGATION. If OPTION=N is specified then the DADSGRF does not need to be defined in your regions.

When BATCH INTERFACE requests are submitted for processing of a VSAM RLS file (either explicitly or within a GROUPID or a CLASS), an ALLOCATE implies that an UNQUIESCE will be issued, and a DEALLOCATE implies a QUIESCE will be issued for that file. If there are entries defined in the SYSID record on the DADSGRF, then RLS PROPAGATION will also occur dynamically when the request is processed. There are three overrides that can be specified when the request is made. These are (1) Option=N for DON'T PROPAGATE, which specifies that this request should be processed in the local CICS region only, and not be propagated to the remote CICS regions specified in the DADSGRF SYSID record. This option is valid for both ALLOCATE and DEALLOCATE requests. (2) OPTION=I for IMMEDIATE QUIESCE , which specifies that the IMMQUIESCED state will be set and that all tasks using the file will be abended by CICS, and then the file will be closed and QUIESCED. This option is only valid for a DEALLOCATE command. (3) Option=U for LEAVE FILE UNQUIESCED, which specifies that for a DEALLOCATE request, the file should be DEALLOCATED without setting the file to QUIESCED state. This option is only valid for a DEALLOCATE command.

On a DEALLOCATE request valid combinations are N, I, U, NI, and NU. On an ALLOCATE request only option N may be specified.

The following are key points for consideration:

1. Using the PROPAGATE function may provide the least SMS server contention. Clients who absolutely need to minimize this should explore using PROPAGATE as opposed to GROUP processing.
   
   
2. CEMT commands cannot be sent to other SYSIDS using PROPAGATE.
   
   
3. Using the PROPAGATE function may end with a return code of 4 in the batch interface if the file is not in all the regions pointed to by the DADRGRF or one of the regions is not available.
   
   
4. GROUPID processing of RLS files must always specify OPTION=N without exception to ensure that GROUPID and PROPAGATION are not performed simultaneously.
   
   
5. GROUPID will generate multiple BATCH INTERFACE REQUESTS, one for every APPLID that belongs to the GROUPID. If the total number of specific requests submitted plus the total number of requests generated (GROUPID) for an individual job step exceeds the documented limit of 1024 then the step will complete with errors.
   
   
6. Clients running a CICSPLEX and WLM environment will want to consider using GROUPID with RLS files, as the files can be QUIESCED/UNQUIESCED when any of the participating regions is available by merely submitting a request to the batch group. DADS Plus for CICS will seek to minimize contention on requests sent to the SMS server, but on occasion simultaneous requests to UNQUIESCE a file can be issued. When this happens, the first request in will perform the actual UNQUIESCE, while other requestors will wait for the UNQUIESCE to be done for them. For clients who seek to completely eliminate this contention, PROPAGATE must be considered as an alternative, or use the technique suggested below.
   
   
7. When using GROUPID for allocation of a VSAM RLS file referenced by multiple CICS regions, there may be some increased SMS server contention on the UNQUIESCE. If this is a concern then first ALLOCATE using OPTION=N, targeting a specific APPLID, which will do the UNQUIESCE. Then in a second step, ALLOCATE for the rest of the APPLIDs or the GROUPID using OPTION= N. DADS Plus will not attempt to UNQUIESCE a VSAM RLS file which is already UNQUIESCED.
   
   An example job stream is as follows:
   
   //STEP1   EXEC PGM=DADBBI&S,REGION=3M
//STEPLIB  DD DISP=SHR,DSN=DADSPLUS.LOADLIB
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
FUNCTION=DADS,APPLID=CICS1REQ=(A,F,FILERLS1),OPTION=N
/*
//STEP2  EXEC PGM=DADBBI&S,REGION=3M
//STEPLIB  DD DISP=SHR,DSN=DADSPLUS.LOADLIB
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
FUNCTION=DADS,GROUPID=RLSGROUPREQ=(A,F,FILERLS1),OPTION=N
/*
   
   
8. When targeting specific APPLIDs, you will need to specify OPTION=N to negate the PROPAGATION feature, which is dynamic. You may also want to consider OPTION=U (leave the file UNQUIESCED) on a DEALLOCATE to minimize SMS server activity. If you want the file to be QUIESCED then one of the APPLID requests can issue the QUIESCE by using only the N option. Use the N and U option on the rest of the APPLIDs so it will not attempt to QUIESCE on all the CICS regions. This will avoid a time out waiting on the SMS server to service the QUIESCE request from the other regions. Once it is QUIESCED on the one region it does not need to be QUIESCED on the other regions.
   
   
9. Propagation for RLS files will not be done by startup processing. A queued request for an RLS file will only be honored on the targeted region.