Storing and using file group definitions (CCAGRP)

Overview

File groups are used to organize cyclic data, to archive aging data, to organize independent but similar files, and to access the same file by different names.

This page provides general information about file groups, followed by instructions on how to create and use a data set containing file group definitions (CCAGRP).

File groups

A file group is a defined list of one or more physically independent but logically related Model 204 files that can be accessed dynamically as a single file. When a group is defined, an entry containing the names of the files in the group is maintained in an internal table in the permanent file group data set CCAGRP.

An individual file can be a member of several different groups and a group can contain as many as 255 Model 204 files. Most installations require only one CCAGRP file.

Commands, SOUL statements, and Host Language Interface calls that refer to a group cause operations to be performed on each member file in turn.

As Model 204 processes an OPEN command for the group, it refers to the internal table, determines which files are associated with that group, and opens each of the member files.

When a FIND statement operates on a group, it acts on each of the member files in turn, resulting in a set of records that includes qualifying records from each of the member files.

Types of file groups

File groups can be permanent, temporary, or ad hoc.

Permanent groups

Permanent groups have the group name and member list stored permanently in the external file CCAGRP until explicitly deleted.

• The system manager creates and maintains permanent groups.
• Any user can open a permanent group.
• Passwords can be required to access the group.
• You cannot create or delete permanent file groups when more than one Model 204 system is running with the same CCAGRP.

Temporary groups

Temporary groups are created by an individual user with the CREATE command and can be referenced only by that user.

• Temporary group names exist only for the current Model 204 login session.
• Temporary group names are deleted when the user logs out, unless the names were explicitly deleted during the session.

Ad hoc groups

Ad hoc groups are created within a SOUL request by prefacing a statement with the following:

IN file1,file2,...

All the files in an ad hoc group must be opened before the group is created.

• Ad hoc groups have no name and exist only for the current request.
• Ad hoc groups facilitate record retrieval from many files at once without requiring that a group be defined in advance.

Using file groups

File groups support dynamic access to multiple, physically independent files that are separately maintained but logically related. Files and file groups can have the same name.

Accessing cyclic data

Cyclic information can be accessed through files containing data segments and then grouped together for access to all the data. An internal table relates the whole (file group) to the segments (files) without data duplication. All the member files need not exist until the group is opened.

For example, file group WEEK consists of the files SUNDAY, MONDAY, TUESDAY, WEDNSDAY (maximum eight letters), THURSDAY, FRIDAY, and SATURDAY. Each daily file is accessible directly under its own name. The union of all files is available under the name WEEK.

Changes made to current members of a group, such as adding new fields or changing field definitions, does not impact the ability to use prior versions of the files in a group. For example, if you keep the five most-recent-fiscal-year files in a group and you then add a new field to the most recent year, you have not disturbed your use of the other files in the group or files older than five years.

Archiving aging data

You can archive aging data without data deletion, file reorganization, or program changes. Once the oldest file is taken offline and archived, changing the group definition allows access to the remaining current files.

For example, if the group WEEK must always contain data from the most recent 7-day period, a new file is created each day and the oldest daily file is taken offline and archived. To preserve the files in chronological order, the group definition is modified to reflect the most recent seven daily files.

Accessing independent but similar data

You can access similar data kept in separate files either by the individual files or by a defined file group and an alternative OPEN command.

For example, if you keep data about individual states in separate files and you need reports for Ohio, a region, and the entire country, you can access the files dynamically using a file group. One user can select a report to be run against the OHIO file. Another user can generate a report for the region, OHIO, INDIANA, and ILLINOIS. Yet another user can generate a report for all 50 states.

Referencing new file names without changing application programs

You can use a file group to reference a new file without changing your application program:

Create a permanent group with the name referenced in the application

1. Define the new file as the only member of the permanent group.
2. If this application is running as an application subsystem, make sure to define both the file and the permanent group in the subsystem definition.

For example, if several application programs operate on FILEA and FILEA is merged with FILEB under the name of FILEC, your application can access FILEC modifications by defining FILEC in a file group called FILEA. (This technique works if the applications use IN syntax rather than IN FILE syntax; see IN clause for more information.)

Updating file groups

In a file group, when you create a new field, the earlier files in the group are unchanged. You can continue to query the database of all the files in the group. You do not need to add the new field to the earlier files. A field need only be present in one file in order to be referenced in a group context.

For example, in time series data, you might want to create a new field and preserve prior data unchanged. You can add a new file in the group containing the new field without affecting earlier files. When you initiate a query, all the files in database group are included in the search.

Creating the CCAGRP data set

Sizing CCAGRP

The size of CCAGRP depends on the maximum number of permanent groups used and the average number of files in a group.

A maximum of 61 group definitions can be stored on one page. This is the number of definitions that fit on a 6184-byte page if the definitions contain an average of nine files. If the average group contains more than nine files, the number of definitions stored on each page is smaller.

The number of pages required is the sum of the number of definition pages, plus three pages for the File Control Table.

Space from deleted groups is reused.

z/OS procedures

In a z/OS environment, take the following steps to create CCAGRP:

1. Turn off the X'02' bit of the SYSOPT parameter.
2. Insert a CCAGRP DD statement (which might have been previously allocated).
3. Insert a system manager login and password in the input stream after User 0's parameter line.
4. Insert the CREATEG command (no arguments) in the CCAIN stream.

   The CREATEG run can also create permanent group definitions by issuing CREATE commands after the CREATEG command.

5. Issue EOJ and bring up the run again with the X'02' bit of SYSOPT turned on. CCAGRP is now accessible to the run.

The following JCL shows a sample batch run that creates CCAGRP.

z/OS JCL example

This sample batch run creates the CCAGRP data set:

// EXEC PGM=BATCH204,REGION=350K, // PARM='SYSOPT=144' //STEPLIB DD DSN=M204.PROGMS,DISP=SHR //CCASTAT DD DSN=M204.CCASTAT,DISP=SHR //CCAAUDIT DD SYSOUT=A //CCATEMP DD UNIT=3330,SPACE=(TRK,5), DISP=(NEW,DELETE) //CCASNAP DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //CCAGRP DD DSN=M204.CCAGRP,UNIT=3330, // SPACE=(TRK,8),DISP=(NEW,CATLG) //CCAPRINT DD SYSOUT=A //CCAIN DD * PAGESZ=6184 LOGIN USERID ---- Log in as system manager PASSWORD ---- System manager password CREATEG EOJ /*

z/VSE procedures

Before you can define permanent file groups to Model 204, you must allocate the CCAGRP file using the ALLOCATE utility.

The Job Control Language statements required for the execution of the ALLOCATE program are:

// JOB ALLOCGRP ALLOCATE MODEL 204 PERMANENT GROUP FILE // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT SYSnnn,... // LIBDEF PHASE.SEARCH=M204LIB.V411 // DLBL CCAGRP,'permanent group file file-id',99/365,SD // EXTENT SYSnnn,balance of extent information // ASSGN SYSnnn,X'cuu' // EXEC ALLOCATE,SIZE=AUTO ALLOCATE FILE(CCAGRP) /* /&

The following considerations apply to executing ONLINE, BATCH204, or user-written IFAM1 programs that use permanent group files:

• Provide the following label information in the execution job stream:

  // DLBL CCAGRP,'permanent group file file-id',,DA // EXTENT SYSnnn,balance of extent information // ASSGN SYSnnn,X'cuu'

• Indicate the use of permanent group files via UPSI switch 6 (SYSOPT=2):

  // UPSI xxxxxx1x

• Define the file type as DA.

z/VM procedures

In a z/VM environment, take the following steps to create CCAGRP:

1. Create a CCAIN file and name it CREATG CCAIN. Include the following statements in the file:

   PAGESZ=6184 LOGON SUPERKLUGE PIGFLOUR CREATEG LOGOFF EOJ

2. Turn off the X'02' bit of the SYSOPT parameter.
3. Create a CREATEG EXEC procedure (see the Rocket Model 204 Installation Guide for IBM z/VM).
4. Insert a FILEDEF for the CREATG CCAIN created above.
5. Create a CCAGRP file by executing the command:

   ONLINE BYPASS CREATEG

Storing group definitions in CCAGRP

Permanent group definitions are stored in the Model 204 file CCAGRP, which must be created before any permanent groups can be defined.

All runs that access permanent file groups require:

• Statement in the JCL defining the CCAGRP file.
• X'02' bit of the SYSOPT parameter. (This lets Model 204 open CCAGRP to the run.)

Including CCAGRP in a Model 204 run does not require changes to the NFILES, NDCBS, or NDIR parameters normally specified. These parameters are automatically advanced by increments during system initialization to make room for CCAGRP.

CCAGRP is opened with UPDATE access during initialization if SYSOPT is set to OPEN CCAGRP. When a Model 204 job runs, it enqueues on CCAGRP in SHARE mode. If a command is entered to create or delete a permanent group, the enqueuing becomes EXCLUSIVE for the duration of the update. Thus, if more than one Model 204 system is running with CCAGRP, no permanent groups can be created or deleted.

Periodically back up permanent group definitions using the DUMPG and RESTOREG commands.

You can delete permanent group definitions from the CCAGRP data set using the DELETE command.

Creating file groups

Use the CREATE command to create both permanent and temporary file groups. Only the system manager can create a permanent group.

Any user can create a temporary file group by entering:

CREATE [TEMP] GROUP groupname FROM filename [, filename ...] [PARAMETER parameter-list] . . . END

At least one file name is required. The following parameters can be included in the list.

Parameter	Description
UPDTFILE	Defines the file that receives stored records unless another file is specified by means of an IN FILE... STORE RECORD statement.
PROCFILE	Defines the group's procedure file.
BLDGFT	Creates a group's field table in memory.

Specifying PROCFILE = * creates a file group in which any or all files can contain procedures.

Examples

The following example shows the creation of a temporary file group:

CREATE GROUP REGION FROM DELAWARE, MARYLAND, VIRGINIA PARAMETER PROCFILE = VIRGINIA, BLDGFT = NO END

The following example creates a permanent file group with multiple procedure files:

CREATE PERM GROUP REGION FROM DELAWARE, MARYLAND, VIRGINIA PARAMETER PROCFILE = *, BLDGFT = NO END

Opening, closing, displaying, and deleting file groups

Opening and closing file groups

You open a file group by entering the OPEN or OPENC command.

OPEN syntax

{OPEN | OPENC} [PERM | TEMP] [GROUP] groupname

OPEN and OPENC operate identically, except that OPENC does not change the existing default. The default value, TEMP, applies when you have a permanent and temporary file group with the same name and do not specify which.

You can open several file groups during a single Model 204 session. They remain open until a CLOSE command is issued.

CLOSE syntax

CLOSE [PERM | TEMP] [GROUP] groupname

Closing a permanent file group closes each file in the group that was opened by a group OPEN. But it does not close files that were opened as individual files or as members of other groups. Closing a temporary file group does not close the files in the group.

Displaying file group information

The DISPLAY command displays information about one or more file groups.

DISPLAY syntax

DISPLAY [PERM | TEMP] GROUP [(display-option [,display-option ...])] {ALL | groupname [,groupname ...]}

If you enter:

DISPLAY GROUP ALL

the group name, status (permanent or temporary), member files, and group parameters are displayed for all the permanent groups and for your temporary groups. You can request that the command display only a list of group names and their status.

Deleting file groups

The DELETE command deletes both permanent and temporary file groups. Only the system manager can delete a permanent file group. Before you can issue the DELETE command for an open file group, you must close the group.

DELETE syntax

DELETE [PERM | TEMP] [GROUP] groupname

File group passwords and privileges

File group passwords

Passwords are specified differently for permanent and temporary file groups. Opening a temporary file group is functionally equivalent to opening a series of files. As each file is opened, you are prompted for the file password, if one is required. The temporary file group is opened only after all the files have been opened.

Permanent file groups can have their own passwords. As with files, there are three types of permanent file groups:

• Public
• Semipublic
• Private

Passwords for semipublic and private file groups are supplied in the manner described for semipublic and private files.

File group privileges

Privileges for a temporary file group are derived from the privileges assigned to the files that make up the group. The privileges granted for a temporary file group are the most restrictive combination of member file privileges. (This combination is defined through a logical AND of the privileges of the individual files in the group.)

For permanent file groups, you can associate a different set of privileges with each group password. The privileges for a group determine which operations you can perform on the data and procedures stored in the group. You can establish default privileges for public and semipublic groups. The system manager enters all these group passwords into the system.