Storing and using file group definitions (CCAGRP) - Revision history

JALWiccan: Automatically generated page update

2014-11-06T17:08:15Z

Automatically generated page update

← Older revision		Revision as of 17:08, 6 November 2014
Line 353:		Line 353:
	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.</p>		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.</p>

	[[Category:System ~~Manager~~]]		[[Category:System management]]
	[[Category:Model 204 operational issues]]		[[Category:Model 204 operational issues]]

JAL at 20:58, 29 October 2014

2014-10-29T20:58:05Z

← Older revision		Revision as of 20:58, 29 October 2014
Line 354:		Line 354:

	[[Category:System Manager]]		[[Category:System Manager]]
			[[Category:Model 204 operational issues]]

JAL: link repair

2014-10-21T21:57:07Z

link repair

← Older revision		Revision as of 21:57, 21 October 2014
Line 255:		Line 255:

	<tr>		<tr>
	<th><var>[[UPDTFILE ~~parameter\|UPDTFILE]]~~</var></th>		<th><var>UPDTFILE</var></th>
	<td>Defines the file that receives stored records unless another file is specified by means of an <code>IN FILE... STORE RECORD</code> statement.</td>		<td>Defines the file that receives stored records unless another file is specified by means of an <code>IN FILE... STORE RECORD</code> statement.</td>
	</tr>		</tr>

	<tr>		<tr>
	<th><var>[[PROCFILE ~~parameter\|PROCFILE]]~~</var></th>		<th><var>PROCFILE</var></th>
	<td>Defines the group's procedure file.</td>		<td>Defines the group's procedure file.</td>
	</tr>		</tr>

	<tr>		<tr>
	<th><var>[[BLDGFT ~~parameter\|BLDGFT]]~~</var></th>		<th><var>BLDGFT</var></th>
	<td>Creates a group's field table in memory.</td>		<td>Creates a group's field table in memory.</td>
	</tr>		</tr>
Line 285:		Line 285:
	END		END
	</p>		</p>

	==Opening, closing, displaying, and deleting file groups==		==Opening, closing, displaying, and deleting file groups==

JAL: minor cleanup

2014-10-21T19:33:07Z

minor cleanup

← Older revision		Revision as of 19:33, 21 October 2014
Line 13:		Line 13:
	Commands, [[SOUL]] statements, and Host Language Interface calls that refer to a group cause operations to be performed on each member file in turn. </p>		Commands, [[SOUL]] statements, and Host Language Interface calls that refer to a group cause operations to be performed on each member file in turn. </p>
	<p>		<p>
	As <var class="product">Model 204</var> 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. </p>		As <var class="product">Model 204</var> processes an <var>OPEN</var> 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. </p>
	<p>		<p>
	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.</p>		When a <var>FIND</var> 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.</p>

	==Types of file groups==		==Types of file groups==
Line 26:		Line 26:
	<ul>		<ul>
	<li>The system manager creates and maintains permanent groups.</li>		<li>The system manager creates and maintains permanent groups.</li>
	~~</li>~~
	<li>Any user can open a permanent group.</li>		<li>Any user can open a permanent group.</li>
	~~</li>~~
	<li>Passwords can be required to access the group.</li>		<li>Passwords can be required to access the group.</li>
	~~</li>~~
	<li>You cannot create or delete permanent file groups when more than one <var class="product">Model 204</var> system is running with the same CCAGRP. </li>		<li>You cannot create or delete permanent file groups when more than one <var class="product">Model 204</var> system is running with the same CCAGRP. </li>
	~~</li>~~
	</ul>		</ul>

Line 40:		Line 39:
	<ul>		<ul>
	<li>Temporary group names exist only for the current <var class="product">Model 204</var> login session.</li>		<li>Temporary group names exist only for the current <var class="product">Model 204</var> login session.</li>
	~~</li>~~
	<li>Temporary group names are deleted when the user logs out, unless the names were explicitly deleted during the session.</li>		<li>Temporary group names are deleted when the user logs out, unless the names were explicitly deleted during the session.</li>
	~~</li>~~
	</ul>		</ul>

Line 54:		Line 52:
	<ul>		<ul>
	<li>Ad hoc groups have no name and exist only for the current request.</li>		<li>Ad hoc groups have no name and exist only for the current request.</li>
	~~</li>~~
	<li>Ad hoc groups facilitate record retrieval from many files at once without requiring that a group be defined in advance. </li>		<li>Ad hoc groups facilitate record retrieval from many files at once without requiring that a group be defined in advance. </li>
	~~</li>~~
	</ul>		</ul>

Line 180:		Line 177:
	<ul>		<ul>
	<li>Provide the following label information in the execution job stream:		<li>Provide the following label information in the execution job stream:
	<p class="code"~~><var~~>// DLBL CCAGRP,'<i>permanent group file file-id</i>',,DA		<p class="code">// DLBL CCAGRP,'<i>permanent group file file-id</i>',,DA
	// EXTENT SYS<i>nnn</i>,<i>balance of extent information</i>		// EXTENT SYS<i>nnn</i>,<i>balance of extent information</i>
	// ASSGN SYS<i>nnn</i>,X'<i>cuu</i>' ~~</var>~~		// ASSGN SYS<i>nnn</i>,X'<i>cuu</i>'
	</p></li>		</p></li>

	<li>Indicate the use of permanent group files via UPSI switch 6 (SYSOPT=2):		<li>Indicate the use of permanent group files via UPSI switch 6 (<code>SYSOPT=2</code>):
	<p class="code">// UPSI <i>xxxxxx</i>1<i>x</i>		<p class="code">// UPSI <i>xxxxxx</i>1<i>x</i>
	</p></li>		</p></li>
Line 213:		Line 210:

	<li>Create a CCAGRP file by executing the command:		<li>Create a CCAGRP file by executing the command:
	<p class="code"~~><var~~>ONLINE BYPASS CREATEG~~</var>~~		<p class="code">ONLINE BYPASS CREATEG
	</p></li>		</p></li>
	</ol>		</ol>
Line 273:		Line 270:
	</table>		</table>
	<p>		<p>
	Specifying <code>PROCFILE = *</code> creates a file group in which any or all files can contain procedures. </p>		Specifying <code>PROCFILE=*</code> creates a file group in which any or all files can contain procedures. </p>

	===Examples===		===Examples===
Line 296:		Line 293:

	====OPEN syntax====		====OPEN syntax====
	<p class="syntax">{OPEN <span class="squareb">\|</span> OPENC} <span class="squareb">[</span>PERM <span class="squareb">\|</span> TEMP<span class="squareb">]</span> <span class="squareb">[</span>GROUP<span class="squareb">]</span> <span class="term">groupname</span>		<p class="syntax"><span class="squareb">{</span>OPEN <span class="squareb">\|</span> OPENC<span class="squareb">}</span> <span class="squareb">[</span>PERM <span class="squareb">\|</span> TEMP<span class="squareb">]</span> <span class="squareb">[</span>GROUP<span class="squareb">]</span> <span class="term">groupname</span>
	</p>		</p>
	<p>		<p>
Line 316:		Line 313:
	<p class="syntax">DISPLAY <span class="squareb">[</span>PERM <span class="squareb">\|</span> TEMP<span class="squareb">]</span> GROUP		<p class="syntax">DISPLAY <span class="squareb">[</span>PERM <span class="squareb">\|</span> TEMP<span class="squareb">]</span> GROUP
	<span class="squareb">[</span>(<span class="term">display-option</span> <span class="squareb">[</span>,<span class="term">display-option</span> ...<span class="squareb">]</span>)<span class="squareb">]</span>		<span class="squareb">[</span>(<span class="term">display-option</span> <span class="squareb">[</span>,<span class="term">display-option</span> ...<span class="squareb">]</span>)<span class="squareb">]</span>
	{ALL <span class="squareb">\|</span> <span class="term">groupname</span> <span class="squareb">[</span>,<span class="term">groupname</span> ...<span class="squareb">]</span>}		<span class="squareb">{</span>ALL <span class="squareb">\|</span> <span class="term">groupname</span> <span class="squareb">[</span>,<span class="term">groupname</span> ...<span class="squareb">]</span><span class="squareb">}</span>
	</p>		</p>
	<p>		<p>

Admin: 1 revision: converted system mgr pages

2014-10-17T20:27:47Z

1 revision: converted system mgr pages

← Older revision	Revision as of 20:27, 17 October 2014
(No difference)

JAL: conversion cleanup

2014-07-17T19:02:16Z

conversion cleanup

New page

==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 <var class="product">Model 204</var> 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 <var class="product">Model 204</var> 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 <var class="product">Model 204</var> 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.
<ul>
<li>The system manager creates and maintains permanent groups.</li>
</li>
<li>Any user can open a permanent group.</li>
</li>
<li>Passwords can be required to access the group.</li>
</li>
<li>You cannot create or delete permanent file groups when more than one <var class="product">Model 204</var> system is running with the same CCAGRP. </li>
</li>
</ul>

===Temporary groups===

Temporary groups are created by an individual user with the <var>CREATE</var> command and can be referenced only by that user. 
<ul>
<li>Temporary group names exist only for the current <var class="product">Model 204</var> login session.</li>
</li>
<li>Temporary group names are deleted when the user logs out, unless the names were explicitly deleted during the session.</li>
</li>
</ul>

===Ad hoc groups===

[[Files, groups, and reference context#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. 
<ul>
<li>Ad hoc groups have no name and exist only for the current request.</li>
</li>
<li>Ad hoc groups facilitate record retrieval from many files at once without requiring that a group be defined in advance. </li>
</li>
</ul>

==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 <code>WEEK</code> 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 <code>WEEK</code>.

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 <code>WEEK</code> 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 <var>OPEN</var> 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====
<ol>
<li>Define the new file as the only member of the permanent group.</li>

<li>If this application is running as an application subsystem, make sure to define both the file and the permanent group in the subsystem definition.</li>
</ol>

For example, if several application programs operate on <code>FILEA</code> and <code>FILEA</code> is merged with <code>FILEB</code> under the name of <code>FILEC</code>, your application can access <code>FILEC</code> modifications by defining <code>FILEC</code> in a file group called <code>FILEA</code>. (This technique works if the applications use <var>IN</var> syntax rather than <var>IN FILE</var> syntax; see [[Files, groups, and reference context#IN clause|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: 

<ol>
<li>Turn off the X'02' bit of the <var>SYSOPT</var> parameter. </li>

<li>Insert a <code>CCAGRP</code> DD statement (which might have been previously allocated).</li>

<li>Insert a system manager login and password in the input stream after User 0's parameter line. </li>

<li>Insert the <var>[[CREATEG command|CREATEG]]</var> command (no arguments) in the CCAIN stream.

The <var>CREATEG</var> run can also create permanent group definitions by issuing <var>CREATE</var> commands after the <var>CREATEG</var> command. 
</li>

<li>Issue <var>EOJ</var> and bring up the run again with the X'02' bit of <var>SYSOPT</var> turned on. CCAGRP is now accessible to the run. </li>
</ol>

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 <var class="product">Model 204</var>, you must allocate the CCAGRP file using the [[ALLOCATE utility in z/VSE|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:
<ul>
<li>Provide the following label information in the execution job stream:
<var>// DLBL CCAGRP,'permanent group file file-id',,DA
// EXTENT SYSnnn,balance of extent information
// ASSGN SYSnnn,X'cuu' </var>
</li>

<li>Indicate the use of permanent group files via UPSI switch 6 (SYSOPT=2):
// UPSI xxxxxx1x
</li>

<li>Define the file type as DA.</li>
</ul>

===z/VM procedures===

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

<ol>
<li>Create a CCAIN file and name it <code>CREATG CCAIN</code>. Include the following statements in the file:
PAGESZ=6184
LOGON SUPERKLUGE
PIGFLOUR
CREATEG
LOGOFF
EOJ


<li>Turn off the X'02' bit of the <var>SYSOPT</var> parameter.</li>

<li>Create a <var>CREATEG EXEC</var> procedure (see the <var class="book">Rocket Model 204 Installation Guide for IBM z/VM</var>).</li>

<li>Insert a FILEDEF for the CREATG CCAIN created above.</li>

<li>Create a CCAGRP file by executing the command:
<var>ONLINE BYPASS CREATEG</var>
</li>
</ol>

==Storing group definitions in CCAGRP==

Permanent group definitions are stored in the <var class="product">Model 204</var> file CCAGRP, which must be created before any permanent groups can be defined. 

All runs that access permanent file groups require:
<ul>
<li>Statement in the JCL defining the CCAGRP file.</li>

<li>X'02' bit of the <var>SYSOPT</var> parameter. (This lets <var class="product">Model 204</var> open CCAGRP to the run.)</li>
</ul>

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

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

Periodically back up permanent group definitions using the <var>[[DUMPG command|DUMPG]]</var> and <var>[[RESTOREG command|RESTOREG]]</var> commands. 

You can delete permanent group definitions from the CCAGRP data set using the <var>[[Files, groups, and reference context#Deleting groups|DELETE]]</var> command.


==Creating file groups==

Use the <var>CREATE</var> 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. 
<table>
<tr class="head">
<th>Parameter</th>
<th>Description</th>
</tr>

<tr>
<th><var>[[UPDTFILE parameter|UPDTFILE]]</var></th>
<td>Defines the file that receives stored records unless another file is specified by means of an <code>IN FILE... STORE RECORD</code> statement.</td>
</tr>

<tr>
<th><var>[[PROCFILE parameter|PROCFILE]]</var></th>
<td>Defines the group's procedure file.</td>
</tr>

<tr>
<th><var>[[BLDGFT parameter|BLDGFT]]</var></th>
<td>Creates a group's field table in memory.</td>
</tr>
</table>

Specifying <code>PROCFILE = *</code> 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 <var>OPEN</var> or <var>OPENC</var> command.

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


<var>OPEN</var> and <var>OPENC</var> operate identically, except that <var>OPENC</var> does not change the existing default. The default value, <var>TEMP</var>, 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 <var class="product">Model 204</var> session. They remain open until a <var>CLOSE</var> 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 <var>OPEN</var>. 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 <var>DISPLAY</var> 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 <var>DELETE</var> command deletes both permanent and temporary file groups. Only the system manager can delete a permanent file group. Before you can issue the <var>DELETE</var> 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: 
<ul>
<li>Public</li>

<li>Semipublic</li>

<li>Private </li>
</ul>

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.

[[Category:System Manager]]