The CICS BAC generic set file enhancement

Requirements and restrictions

1. The GSF command is only available using the CICS BAC Batch Request Utility.
2. GSF commands only support a single trailing generic character (“*”) — a single asterisk as the last character in the command’s file name. Embedded generics or wildcards (for example, “A?B”, “A*B”, or A*B*”) are not supported. At least one valid character before the generic character is required. For example, “A*” is a valid generic name, whereas “*” is not. Note that in the previous examples, the double quotes are not part of the generic file name.
3. GSF commands search only the target CICS region’s CICS BAC control file for matching file names. A matching file name that is defined to CICS, but is not in the CICS BAC control file is not included in the command processing. In order to be available for GSF command processing, a file must have previously been added to the CICS BAC control file using one of the existing methods provided by CICS BAC. The GSF enhancement does not include any new methods for adding files to the CICS BAC control file.
4. For consistency, the GSF command optional parameters are limited to those supported by the CICS BAC SET GROUP command – OPENSTATUS, ENABLESTATUS, IMMQUIESCE, DSN, and CICS, along with the READ, BROWSE, ALLREAD, UPDATE, ADD, DELETE, and ALLUPDATE parameters. Any other parameters detected on a GSF command are flagged as an error and the CICS BAC BRU terminates with a non-zero condition code.
5. A new Batch Request Utility runtime parameter has been introduced to enable and disable the generic set file function. The default value for this parameter is to disallow generic set file commands so that processing for existing customers— failing a SET FILE command with a generic file name, remains the same without any action by the customer.
6. A generic file name cannot be used anywhere else in CICS BAC, for example, it cannot be used to define multiple files in a SET GROUP command. The only exception to this restriction is that generic file names continue to be supported by features and functions that support them today, for example, the CICS BAC File Maintenance Utility’s LIST FILE command.
7. If a GSF command contains the IMMQUIESCE parameter, and the generic file name results in the selection of one or more non-RLS data sets, the IMMQUIESCE parameter and value is ignored for the non-RLS data sets.

Processing overview

When a CICS BAC Batch Request Utility job step encounters a SET FILE command containing a generic file name, and CICS BAC is available in the target CICS region, the following processing takes place:

1. If GSF commands are “turned off”, the BRU fails the command with an “invalid parameter value” error.
2. If GSF commands are “turned on”, the BRU verifies that the generic file name meets the requirements — a single asterisk as the last character of the name, and at least one valid character before the asterisk. If the file name does not meet the requirements, the command fails with an “invalid parameter value” error.
3. If the file name does meet the requirements, the BRU sends the command to the target CICS region under the same rules as it processes all other commands, for example, the command can be “batched” and delivered with other commands, and commands from multiple BRU job steps targeting the same CICS region are serialized.
4. When CICS BAC (running in the target CICS region) detects a generic SET FILE command, it builds a temporary, in memory only, CICS BAC Group record. To do this, CICS BAC reads the target region’s CICS BAC control file to extract the file names of all of the file resource object records with a file name that matches the generic file name provided by the command.
5. Each matching file name becomes an entry in the temporary CICS BAC Group record. As with normal, “permanent” CICS BAC group records, the temporary group record can hold a maximum of 512 “resource objects”. If the 512 name maximum is exceeded, the BRU command (and job step) is terminated with a non-zero condition code and error message.
6. After the temporary group record has been created, CICS BAC processes the command logically the same as it does a normal group record. Parameters provided on the GSF command are applied to each of the files in the temporary group. The files are processed in the sequence they are encountered — in sorted order since they were initially retrieved from the control file in sorted order.
7. Processing continues until the last file in the temporary group is processed, or an error occurs that requires CICS BAC to terminate the processing of the GSF command. In the latter case, the BRU job step also terminates with either a non-zero condition code or an abend code, depending on the error. In some cases, due to user option settings, an error may be “ignored” — processing does not terminate. For example, if a file is defined as “excluded” from CICS BAC processing, and the action chosen for the exclusion is “ignore”, CICS BAC writes appropriate log records to the audit file (if it is enabled), but processing continues with the next file in the group, if there are any.
8. CICS BAC audit log records are written in a nearly identical fashion as they are for normal group processing:
   • A “START” log record is written to mark the beginning of the GSF command processing. The type of record is “GENFILE”. The generic file name is part of the log message.
   • One or more log records are written to show what processing takes place for each file. These log records are identical to the ones written when members of a normal group are processed.
   • When processing for the GSF command is complete, a “END” log record is written to the audit log.
9. The temporary “in memory” group record is “released” when processing for the GSF command is complete in the CICS region.
10. For all other processing, CICS BAC performs as it does without the GSF enhancement.
11. Messages are written to the BRU job step’s CBKPRINT output destination that are logically equivalent to what is currently written.