Operating System BS2000 OS DX V1.0 (en)

&pagelevel(3)&pagelevel

Define name and attributes of new file generation group

Component:	BS2000
Functional area:	File processing
Domain:	FILE-GENERATION-GROUP
Privileges:	STD-PROCESSING TSOS
Routing code:	$ (with NBCONOPI=N) or E (with NBCONOPI=Y)

Function

The CREATE-FILE-GROUP command creates the catalog entry for a new file generation group on disk.

File generation groups (FGGs) consist of a group entry and the associated file generations. The group entry is created with the CREATE-FILE-GROUP command and can be modified with the MODIFY-FILE-GROUP-ATTRIBUTES command. File generations are created with the CREATE-FILE-GENERATION command and can be modified with the MODIFY-FILE-GENERATION-SUPPORT command. The file protection and data backup attributes defined in the group entry also apply to the associated file generations. User and systems support information (see USER- and ADM-INFORMATION operands) in the group entry is not “bequeathed” to the generations. This information can be defined separately for each file generation whenever a generation is created or modified.

FGGs can be created on public disks, private disks or in an nonhomogeneous mix, with the group entry on public disk and the associated file generations both on tape and on public disk. FGGs cannot be created on Net-Storage.

FGGs are not saved in the version backup archive, that means the NUM-OF-BACKUP-VERS has the value 0.

FGGs which are held on private volumes and for which there is no catalog entry are designated as exported or “FOREIGN” file generation groups. If such a FGG is to be recataloged, the group entry must be imported first, followed by the associated file generations (using the IMPORT-FILE command).

If no group entry is available for existing file generations (on private volumes or as a result of a system error in the file catalog), the CREATE-FILE-GROUP command can be used to create a new group entry for the existing file generations. This entails specifying where the generations start and finish using the FIRST-GENERATION and LAST-GENERATION operands. If the generations are on private volumes, they must then be imported with the IMPORT-FILE command.

The following must be noted for file generations on tape:

If the FGG is protected by BASIC-ACL or, in conjunction with the SECOS software product, by GUARDS (see the “SECOS” manual [35]), these protection mechanisms are recorded only in the file catalog, not in the tape labels. In this case, the conventional protection mechanisms - standard access control (ACCESS and USER-ACCESS) and passwords - must be used to protect tape files against unauthorized access.

Unlike an FGG which merely has ACCESS=*READ write protection, an FGG “write protected” by BASIC-ACL or GUARDS cannot be extended by creating a new file generation.

Privileged functions

Systems support personnel can supplement the user information in the file catalog with one to eight bytes of information about the file generation group (ADM-INFORMATION operand).

By default, systems support (TSOS privilege) is a co-owner of all the files (and can, therefore, create file generation groups under all user logons). When SECOS is used, this co-ownership can be restricted. In conjunction with the SECOS software product a user can allow other user IDs to act as co-owners of the file generation groups of his user ID. Co-owners of a user ID are then also allowed to create file generations under that ID.

File generation groups in SM pubsets

A file generation group for standard files or for work files can be created in an SM pubset. This is done with the STOR-CLASS-DEFAULT operand, either explicitly (using the WORK-FILE-GROUP operand in the STOR-CLASS-DEFAULT=*NONE(...)) structure or implicitly by assigning a default storage class with the corresponding WORK-FILE attribute. All the file generations in the FGG must have the same WORK-FILE attribute. The WORK-FILE attribute cannot be modified later.

Assigning a storage class simplifies the automatic management of storage space (for details see the “Introduction to System Administration” [14] or the “System-Managed Storage” manual [45]).

Overview of functions

Function / Meaning	Level 1 operands	Level 2/3 operands
Define name of the file generation group	GROUP-NAME =
Define general attributes of file generation group	GENERATION- PARAMETER =
Maximum permitted number of generations		MAXIMUM
Action when this number exceeded		OVERFLOW-OPTION
Base number absolute relative to last file generation		BASE-NUMBER =RELATIVE-TO-LAST- GEN =RELATIVE-TO-LAST- GEN
Number of first generation		FIRST-GENERATION
Number of last generation		LAST-GENERATION
Specify device type		DEVICE-TYPE
Specify the volume		VOLUME
Define protection attributes	PROTECTION = *PARAMETERS(...)
Import protection attributes from file		PROTECTION-ATTR
File access rights		ACCESS
Shareability		USER-ACCESS
Basic access control list		BASIC-ACL
Password protection		PASSWORD
Define passwords		WRITE-PASSWORD/ READ-PASSWORD
Physical deletion (overwrite with binary zeros)		DESTROY-BY-DELETE
Monitoring of DMS accesses via SAT/System Exit Routines		AUDIT
Lock to prevent release of reserved storage space (disk files only)		SPACE-RELEASE-LOCK
Date of release for deletion		FREE-FOR-DELETION
Specify default storage class	STOR-CLASS-DEFAULT =
No default storage class	STOR-CLASS-DEFAULT = *NONE(...)
Work file attribute		WORK-FILE-GROUP
For disk files only: Type and frequency of automatic data backup by ARCHIVE or HSMS	SAVE
Backup frequency		BACKUP-CLASS
Scope of backup		SAVED-PAGES
HSMS storage management class	MANAGEMENT-CLASS
Code table (XHCS)	CODED-CHARACTER-SET
HSMS storage management class	MANAGEMENT-CLASS
user information	USER-INFORMATION
systems support information	ADM-INFORMATION

Table 37: Overview of CREATE-FILE-GROUP command functions

Format

CREATE-FILE-GROUP

Alias: CRFGP

GROUP-NAME = <filename 1..47 without-gen-vers>

,GENERATION-PARAMETER = [ *GEN ERATION -PAR AMETER ] (...)

[ *GEN ERATION -PAR AMETER ](...)

|

MAXIMUM = <integer 1..255>

|

,OVERFLOW-OPTION = *CYCL IC -REPL ACE / *REUSE-VOLUME / *DELETE-ALL /

|

*KEEP-GENERATION

|

,BASE-NUMBER = *EQU AL -FIRST -GEN / <integer 1..9999>

|

,FIRST-GENERATION = 0 / <integer 0..9999>

|

,LAST-GENERATION = 0 / <integer 0..9999>

|

,DEVICE-TYPE = *BY-VOL UME / <device>

|

,VOLUME = *PUB LIC / <alphanum-name 1..6>

,PROTECTION = *STD / [*PARAMETERS](...)

[*PARAMETERS](...)

|

PROTECTION-ATTR = *BY-DEF-PROT-OR-STD / *STD / *FROM-FILE(...)

|

*FROM-FILE(...)

|

FILE-NAME = <filename 1..54 without-gen>

|

,ACCESS = *BY-PROTECTION -ATTR / *WRITE / *READ

|

,USER-ACCESS = *BY-PROTECTION -ATTR / *OWNER-ONLY / *ALL-USERS

|

,BASIC-ACL = *BY-PROTECTION -ATTR / *NONE / *STD / *PARAMETERS(...) / *GROUP-R /

|

*GROUP-WR / *ALL-R / *ALL-WR

|

*PARAMETERS(...)

|

OWNER = *NO-ACCESS / *PARAMETERS(...)

|

*PARAMETERS(...)

|

READ = *NO / *YES

|

,WRITE = *NO / *YES

|

,GROUP = *NO-ACCESS / *PARAMETERS(...)

|

*PARAMETERS(...)

|

READ = *NO / *YES

|

,WRITE = *NO / *YES

|

,OTHERS = *NO-ACCESS / *PARAMETERS(...)

|

*PARAMETERS(...)

|

READ = *NO / *YES

|

,WRITE = *NO / *YES

|

,GUARDS = *BY-PROTECTION -ATTR / *NONE / *PARAMETERS(...)

|

*PARAMETERS(...)

|

READ = *NONE / <filename 1..18 without-cat-gen-vers>

|

,WRITE = *NONE / <filename 1..18 without-cat-gen-vers>

|

,WRITE-PASSWORD = *BY-PROT-ATTR-OR-NONE / *NONE / <c-string 1..4> / <x-string 1..8> /

|

<integer -2147483648..2147483647> / *SECRET

|

,READ-PASSWORD = *BY-PROT-ATTR-OR-NONE / *NONE / <c-string 1..4> / <x-string 1..8> /

|

<integer -2147483648..2147483647> / *SECRET

|

,DESTROY-BY-DELETE = *BY-PROT ECTION -ATTR / *NO / *YES

|

,AUDIT = *STD / *NONE / *SUCCESS / *FAILURE / *ALL

|

,SPACE-RELEASE-LOCK = *BY-PROTECTION-ATTR / *NO / *YES

|

,FREE-FOR-DELETION = *NONE / <date> / <integer 0..991231>

,SAVE = *STD / *NO / [*PARAMETERS](...)

[*PARAMETERS](...)

|

BACKUP-CLASS = *STD / *A / *B / *C / *D / *E

|

,SAVED-PAGES = *COMPLETE-FILE / *MODIFIED-PAGES

,MANAGEMENT-CLASS = *NONE / <composed-name 1..8>

,CODED-CHARACTER-SET = *USER-DEFAULT / *NONE / <name 1..8>

,USER-INFORMATION = *NONE / <c-string 1..8 with-low>

,ADM-INFORMATION = *NONE / <c-string 1..8 with-low>

,STOR-CLASS-DEFAULT = *STD / <composed-name 1..8> / *NONE(...)

*NONE(...)

|

WORK-FILE-GROUP = *NO / *YES

Operands

GROUP-NAME = <filename 1..47 without-gen-vers>
The name to be given to the file generation group.
Only the user’s own user ID or a user ID for which the user is co-owner may be specified. Systems support personnel (TSOS privilege) may specify any user ID.

GENERATION-PARAMETER = *GENERATION-PARAMETER(...)
Specifies the attributes of the file generation group.

MAXIMUM = <integer 1..255>
Defines how many generations of the file generation group may be cataloged at the same time (see the OVERFLOW-OPTION operand).

OVERFLOW-OPTION = *CYCLIC-REPLACE / *REUSE-VOLUME / *DELETE-ALL / *KEEP-GENERATION
Specifies what should be done if the maximum permitted number of file generations (MAXIMUM operand) is exceeded. When the maximum permitted number is reached, the surplus file generations will be deleted regardless of password protection, retention period (EXPIRATION-DATE) and the permitted mode of access (ACCESS).

OVERFLOW-OPTION = *CYCLIC-REPLACE
The current oldest generation is deleted and its storage space, or the tapes it occupies, are released. In the catalog, the entries in the LAST-GEN and FIRST-GEN output fields (most recent/oldest existing generations) are updated.

OVERFLOW-OPTION = *REUSE-VOLUME
The effect of OVERFLOW-OPTION=*REUSE-VOLUME depends on the storage medium:

For FGGs on public disks: the oldest generation will be deleted and its storage space returned to the system; the group entry is updated (see OVERFLOW-OPTION= *CYCLIC-REPLACE).

For FGGs on private disks: the new generation is created and the oldest generation deleted, the volume being used for storage of the new generation. If the generation which is being deleted extends over several disks, the new generation is cataloged only on the first of these disks. The group entry is updated accordingly. Since the old generation is not deleted until the new generation has been created, lack of storage space on the disk may mean that it is impossible to create the new generation, even though OVERFLOW-OPTION=*REUSE-VOLUME is specified.

For FGGs on tape: the oldest generation is deleted from the catalog, and the new generation is created on the tape thus released. The group entry is updated accordingly. OVERFLOW-OPTION=*REUSE-VOLUME is not permitted for file generation groups on multifile tapes (file sets).

OVERFLOW-OPTION = *DELETE-ALL
All generations of the FGG are deleted, and the new generation becomes the oldest one in the new series. The group entry is updated accordingly.

OVERFLOW-OPTION = *KEEP-GENERATION
The file generations are not automatically deleted. The oldest file generations which overshoot the maximum will not be deleted until OVERFLOW-OPTION or BASE-NUMBER is modified (MODIFY-FILE-GROUP-ATTRIBUTES command).

BASE-NUMBER = *EQUAL-FIRST-GEN / <integer 0..9999>
Defines a reference point/a base generation to which all relative generation numbers refer. The names of the file generations can be specified with absolute (*n) or relative (±n) generation numbers.

BASE-NUMBER = *EQUAL-FIRST-GEN
The starting base is the value specified by FIRST-GENERATION.

FIRST-GENERATION = 0 / <integer 1..9999>
Specifies the absolute generation number of the oldest existing file generation. The operand should be used only in combination with the LAST-GENERATION operand in order to reconstruct the group entry of a file generation group. This needs to be done in order to work with existing file generations for which no group entry exists (see the "Function" description).

LAST-GENERATION = 0 / <integer 0..9999>
Specifies the absolute generation number of the most recent existing file generation. The operand should be used only in combination with the FIRST-GENERATION operand in order to reconstruct the group entry of a file generation group. This needs to be done in order to work with existing file generations for which no group entry exists (see the "Function" description).

DEVICE-TYPE = *BY-VOLUME / <device>
The type of device to which the required disk is assigned (if the file generation group is to be created on a private disk).

DEVICE-TYPE = *BY-VOLUME
File generation groups on public volumes:
The system itself determines the device type. If the file generation group is being set up on a public disk, (VOLUME=*PUBLIC), then the only permissible specification is *BY-VOLUME.

DEVICE-TYPE = <device>
File generation groups on private volumes:
If the file generation group is being set up on a private disk, then the device type must be explicitly specified here (*BY-VOLUME is not allowed). Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types. If at least one volume ID is specified with VOLUME, each specification of a disk device type which is known to the system is handled like the STDDISK specification. The permissible specifications for DEVICE-TYPE can also be found in the device table in section "Device type table" (device type column).

VOLUME = *PUBLIC / <alphanum-name 1..6>
VSN of the public/private disk on which the file generation is to be created.

VOLUME = *PUBLIC
The file generation group will be created on a public disk. The generations which belong to it can also be set up on tapes or tape cartridges.

VOLUME = <alphanum-name 1..6>
The file generation group will be created on a private disk. The generations which belong to it must also be set up on a private disk.

PROTECTION = *STD / *PARAMETERS(...)
The protection attributes for the file.

PROTECTION = *STD
The protection attributes listed below are assigned the values supplied by default protection.
If default protection is not active, the system default values for the operands of the *PARAMETERS structure are set.

Protection attribute	PROTECTION-ATTR=
	*FROM-FILE	*STD¹⁾	*BY-DEF-PROT-OR-STD
	*FROM-FILE	*STD¹⁾	Default protection not active¹⁾	Default protection active
ACCESS	value from reference file	WRITE	WRITE	values from default protection
USER-ACCESS		OWNER-ONLY	OWNER-ONLY
BASIC-ACL		NONE	NONE
DESTROY-BY-DELETE		NO	NO
GUARDS		NONE	NONE
SPACE-RELEASE-LOCK		NO	NO
READ-PASSWORD	NONE	NONE	NONE
WRITE-PASSWORD	NONE	NONE	NONE
EXEC-PASSWORD	NONE	NONE	NONE
FREE-FOR-DELETION	NONE	NONE	NONE	NONE
AUDIT	NONE	NONE	NONE	NONE

¹⁾The system default values are entered.
Table 38: Effects of PROTECTION-ATTR on the protection attributes in the case of CREATE-FILE-GROUP

PROTECTION = *PARAMETERS(...)
The file generation group is given the specified protection attributes. For descriptions of the PROTECTION-ATTR, ACCESS, USER-ACCESS, BASIC-ACL, GUARDS, WRITE-PASSWORD, READ-PASSWORD, DESTROY-BY-DELETE, AUDIT, SPACE-RELEASE-LOCK and FREE-FOR-DELETION operands, see the corresponding operand descriptions for the CREATE-FILE command.

Note the following

Since file generations are not executable (program or procedure), they cannot be protected with an execute password (EXEC-PASSWORD). Likewise for the same reason no execute permission can be set within BASIC-ACL or GUARDS.

SAVE = ..., MANAGEMENT-CLASS = ..., CODED-CHARACTER-SET = ..., USER-INFORMATION = ...,
ADM-INFORMATION = ...
See the description of the corresponding operand in the CREATE-FILE command.

STOR-CLASS-DEFAULT = *STD / <composed-name 1..8> / *NONE(...)
The operand is evaluated only for file generation groups in SM pubsets. Governs the properties of the storage location if no explicit specification is made when the file generation is created. Only the “work file” attribute is copied from a specified storage class into the group entry, and it then governs whether the associated generations are work files or standard files.

The only specification allowed for a file generation group in an SF pubset is STOR-CLASS-DEFAULT=*NONE.

The SHOW-STORAGE-CLASS command allows users to find out which storage classes of an SM pubset are available to them and which file attributes are set.

Assigning a storage class simplifies the automatic management of storage space in an SM pubset (for details see the “Introduction to System Administration” [14] or the “System-Managed Storage” manual [45]).

STOR-CLASS-DEFAULT = *STD
The pubset-specific default storage class from the user entry is used as the default storage class for the file generation group. If the file generation group is to be created in an SF pubset or if there is no default storage class defined in the user entry, the file generation group is given the same attributes as with STOR-CLASS-DEFAULT=*NONE with default values.

STOR-CLASS-DEFAULT = <composed-name 1..8>
A file generation group in an SM pubset is assigned the specified storage class. The storage class must exist and be accessible to the user at the time when the assignment is made. This specification is ignored for a file generation group in an SF pubset; the FGG is then given the same attributes as with STOR-CLASS-DEFAULT=*NONE with default values.

STOR-CLASS-DEFAULT = *NONE(...)
This value has the same effect as *STD if all the following conditions are met:

The file generation group is created on a volume set intended for permanent storage.
A default storage class is assigned to the user ID at the SM pubset in question.
Physical allocation is not permitted.

Only in this case is the WORK-FILE-GROUP operand ignored.

In all other cases, no storage class is assigned to the file generation group.

WORK-FILE-GROUP = *NO / *YES
The operand is evaluated only for file generation groups in SM pubsets. Specifies whether the associated file generations are work files which systems support is allowed to delete at a time which it defines.

WORK-FILE-GROUP = *NO
The associated file generations are not to be work files.

WORK-FILE-GROUP = *YES
The associated file generations are to be work files.

Return codes

(SC2)	SC1	Maincode	Meaning/Guaranteed messages
	0	CMD0001	Command executed
2	0	DMS06CA	Command executed, but invalid specification in BASE-NUMBER operand ignored
	1	CMD0202	Syntactical or semantic error in command
	32	DMS0584	A state that does not allow the function to continue was reported during processing
	32	DMS05C7	Unexpected internal error in DMS
	64	CMD0216	Privileges error
	64	DMS0501	Requested catalog not available
	64	DMS0512	Requested catalog not available
	64	DMS051B	Requested user ID not in pubset Guaranteed messages: DMS051B, DMS0681
	64	DMS051C	User not authorized to access pubset Guaranteed messages: DMS051C, DMS0681
	64	DMS053E	File already cataloged on private volume
	64	DMS0579	Invalid operand for temporary file or work file
	64	DMS057B	Invalid operand for migrated file
	64	DMS057C	Processing not possible due to HSMS error
	64	DMS057E	File has been migrated, and HSMS is not available
	64	DMS057F	Renaming of migrated file not permitted
	64	DMS0585	Error detected during catalog processing or multihost processing
	64	DMS0586	Currently not possible to access or reserve volume
	64	DMS0587	Use of specified command restricted by system administrator
	64	DMS0588	It was not possible to allocate disk space
	64	DMS059F	Specified value for number of backup versions invalid
	64	DMS05B5	Guard not available
	64	DMS05CC	File name already cataloged
	64	DMS05FC	Specified user ID not in HOME pubset
	64	DMS060D	Invalid file name for reference file (PROTECTION-ATTR)
	64	DMS0613	Unknown management class
	64	DMS0618	Unknown storage class
	64	DMS061A	Storage class catalog could not be read
	64	DMS06FF	BCAM connection severed
	128	DMS0506	Function not executed due to change in master
	130	DMS0524	System address space full
	130	DMS053C	No space in pubset catalog file Guaranteed messages: DMS053C
	130	DMS0585	Error detected during catalog processing or multihost processing
	130	DMS0586	Currently not possible to access or reserve volume
	130	DMS0594	Not enough virtual memory available
	130	DMS05C8	Maximum permitted number of files reached

Examples

Examples of the use of the CREATE-FILE-GROUP command are given in the examples for the CREATE-FILE-GENERATION command.

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

CREATE-FILE-GROUP

Function

Privileged functions

File generation groups in SM pubsets

Overview of functions

Format

Operands

Return codes

Examples