Operating System BS2000 OS DX V1.0 (en)

&pagelevel(3)&pagelevel

Modify device assignment and space allocation of file generations

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 MODIFY-FILE-GENERATION-SUPPORT command amends the device assignment and storage space allocation for an existing file generation. Only the owner, any co-owners (see “Privileged functions”) and systems support personnel are allowed to modify all of a file generation’s attributes. Other users, provided they have write permission for the file generation, are allowed only to allocate extra space or tapes.

The file protection and data backup attributes are defined once only for the entire file generation group using the CREATE-FILE-GROUP command and modified using the MODIFY-FILE-GROUP-ATTRIBUTES command. User and systems support information (see the USER-INFORMATION and ADM-INFORMATION operands) is not copied from the group entry but can be defined separately for each file generation.

The default value *UNCHANGED in the corresponding operands means that the previously valid definition still applies.

Privileged functions

The following functions are available to nonprivileged users only if physical allocation of public space is allowed (see “Privileged functions” in the function description of the CREATE-FILE command):

explicit specification (values other than the default, *STD) of a volume or volume set in the VOLUME and VOLUME-SET operands in the structure SUPPORT=*PUBLIC-DISK (STORAGE-CLASS=*NONE(...))
absolute space reservation using SPACE=*ABSOLUTE(...) in the structure SUPPORT=*PUBLIC-DISK(...)

Exception: Privileged functions are not available for work files if no authorization for physical allocation is given.

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

By default, systems support (TSOS privilege) is a co-owner of all the files and file generations (and can, therefore, modify their catalog entries). When SECOS is used, this co-ownership can be restricted for permanent files.

Verifying command execution

The DIALOG-CONTROL operand governs whether a verification dialog is to be conducted with the user. The OUTPUT operand lets the user specify whether each file name that is processed is to be logged in a guaranteed message to SYSOUT. In conjunction with the chargeable SDF-P subsystem, the processed file names can be viewed in the S variable stream for guaranteed messages (SYSMSG; see also the ASSIGN-STREAM and EXECUTE-CMD commands in the “SDF-P” manual [34]).

File generations in SM pubsets

The storage location for a file generation on an SM pubset can be selected on the basis of a storage class. This simplifies the automatic management of storage space on an
SM pubset (for details see the “Introduction to System Administration” [14] or the “System-Managed Storage” manual [45]). Systems support personnel allocates to a storage class certain file attributes which are implicitly set for all files assigned to that storage class. If a storage class is specified, there is no need to explicitly specify values for the WORK-FILE, VOLUME-SET, VOLUME, DEVICE-TYPE, IO-ATTRIBUTES, DISK-WRITE, FILE-PREFORMAT and AVAILABILITY operands. The SHOW-STORAGE-CLASS command allows users to find out which storage classes of the SM pubset are available to them and which file attributes are set.

If the requirements for the file generation’s storage location are changed (explicitly or implicitly by way of the storage class), the storage location may change automatically, with the result that the file is moved to a different volume set. The change of storage location is a synchronous process involving copying of the file generation. The file generation is not accessible to other tasks while copying is in progress.

Overview of functions

Function / Meaning	Level 1 operands	Level 2/3 operands
The name of the file generation concerned	GENERATION-NAME
Specify the volume	SUPPORT
Volume: pubset	SUPPORT = *PUBLIC-DISK(...)
Specify storage class		STORAGE-CLASS
Performance requirements performance attribute type of I/O operations		IO-ATTRIBUTES PERFORMANCE USAGE
Define time when data consistency is required after write operations		DISK-WRITE
Define availability requirements		AVAILABILITY
preferred file format		FILE-PREFORMAT
Specify volume sets		VOLUME-SET
Specify the volume		VOLUME
Specify device type		DEVICE-TYPE
Change of volume set allowed		S0-MIGRATION
user information		USER-INFORMATION
systems support information		ADM-INFORMATION
Volume: private disk	= *PRIVATE-DISK
Specify device type		DEVICE-TYPE
Request volume(s)		VOLUME
Storage space allocation (allocate, change, release)		SPACE
Time of disk mounting		VOLUME-ALLOCATION
Separate storage of data/index for ISAM files		DATA-SUPPORT
Volume: pubset or private disk	= *ANY-DISK
Specify device type		DEVICE-TYPE
Specify the volume		VOLUME
Storage space allocation (allocate,change, release)		SPACE
Volume: tape	= *TAPE
Specify device type		DEVICE-TYPE
Request volume(s)		VOLUME
Request tape device		PREMOUNT-LIST
Verification of multiple file specifications
File selection dialog	DIALOG-CONTROL
User intervention in command execution not possible (default setting for procedures and batch mode)	=*NO
Dialog when more than one file is referenced if the file name specified is not fully qualified (default setting for interactive mode)	=*MORE-THAN-ONE-FILE
Dialog when an error occurs	=*ERROR
Dialog when catalog ID changes	=*CATALOG-CHANGE
Dialog for each selected file that is to be processed	=*FILE-CHANGE
Dialog when user ID changes	=*USER-ID-CHANGE
Message for successfully modified catalog entries	OUTPUT
Suppress	=*NO
Output to SYSOUT	=*SYSOUT

Table 60: Overview of MODIFY-FILE-GENERATION-SUPPORT command functions

Format

MODIFY-FILE-GENERATION-SUPPORT

Alias: MDFGNS

GENERATION-NAME = <filename 1..54 without-vers with-wild(80)>
,SUPPORT = UNCHANGED / PUBLIC-DISK(...) / PRIVATE-DISK(...) / ANY-DISK(...) / *TAPE(...)
	*PUBLIC-DISK(...)
		\|	STORAGE-CLASS = UNCHANGED / STD / UPDATE / <composed-name 1..8> / NONE(...)
		\|		*NONE(...)
		\|			\|	IO-ATTRIBUTES = UNCHANGED / *PARAMETERS(...)
		\|			\|		*PARAMETERS(...)
		\|			\|			\|	PERFORMANCE = UNCHANGED / STD / HIGH / VERY-HIGH /
		\|			\|			\|		*USER-MAXIMUM
		\|			\|			\|	,USAGE = UNCHANGED / READ-WRITE / WRITE / READ*
		\|			\|	,DISK-WRITE = UNCHANGED / IMMEDIATE / *BY-CLOSE
		\|			\|	,AVAILABILITY = UNCHANGED / STD / *HIGH
		\|			\|	,FILE-PREFORMAT = STD / K / NK2 / NK4
		\|			\|	,VOLUME-SET = STD / CONTROL-VOLUME-SET / <cat-id 1..4>
		\|			\|	,VOLUME = *UNCHANGED / list-poss(255): <vsn 1..6>
		\|			\|	,DEVICE-TYPE = *UNCHANGED / <device>
		\|			\|	,S0-MIGRATION = UNCHANGED / ALLOWED / *FORBIDDEN
		\|	,SPACE = UNCHANGED / RELATIVE(...) / ABSOLUTE(...) / RELEASE(...)
		\|		*RELATIVE(...)
		\|			\|	PRIMARY-ALLOCATION = 0 / <integer 0..2147483647>
		\|			\|	,SECONDARY-ALLOCATION = *UNCHANGED / <integer 0..32767>
		\|		*ABSOLUTE(...)
		\|			\|	FIRST-PAGE = <integer 1..2147483647>
		\|			\|	,SIZE = <integer 1..2147483647>
		\|		*RELEASE(...)
		\|			\|	NUMBER-OF-PAGES = <integer 1..2147483647> / *ALL-RELEASABLE
		\|			\|	,KEEP-MIN-ALLOCATION = NO / YES
		\|	,USER-INFORMATION = UNCHANGED / NONE / <c-string 1..8 with-low>
		\|	,ADM-INFORMATION = UNCHANGED / NONE / <c-string 1..8 with-low>
	*PRIVATE-DISK(...)
		\|	VOLUME = UNCHANGED / [ANY](...) / list-poss(255): <alphanum-name 1..6>
		\|		[*ANY](...)
		\|			\|	NUMBER-OF-DEVICES = 1 / <integer 1..9>
		\|	,DEVICE-TYPE = *UNCHANGED / <device>
		\|	,SPACE = UNCHANGED / RELATIVE(...) / RELEASE(...) / ABSOLUTE(...)
		\|		*RELATIVE(...)
		\|			\|	PRIMARY-ALLOCATION = 0 / <integer 0..2147483647>
		\|			\|	,SECONDARY-ALLOCATION = *UNCHANGED / <integer 0..32767>
		\|		*RELEASE(...)
		\|			\|	NUMBER-OF-PAGES = <integer 1..2147483647> / *ALL-RELEASABLE
		\|		*ABSOLUTE(...)
		\|			\|	FIRST-PAGE = <integer 1..2147483647>
		\|			\|	,SIZE = <integer 1..2147483647>
		\|	,VOLUME-ALLOCATION = IMMEDIATE / DELAYED
		\|	,DATA-SUPPORT = UNCHANGED / [PARAMETERS](...)
		\|		[*PARAMETERS](...)
		\|			\|	DATA-DEVICE-TYPE = *UNCHANGED / <device>
		\|			\|	,DATA-VOLUME = *UNCHANGED / list-poss(255): <alphanum-name 1..6>
		\|			\|	,DATA-SPACE = RELATIVE(...) / ABSOLUTE(...)
		\|			\|		*RELATIVE(...)
		\|			\|			\|	PRIMARY-ALLOCATION = 0 / <integer 0..2147483647>
		\|			\|			\|	,SECONDARY-ALLOCATION = *UNCHANGED / <integer 0..32767>
		\|			\|		*ABSOLUTE(...)
		\|			\|			\|	FIRST-PAGE = <integer 1..2147483647>
		\|			\|			\|	,SIZE = <integer 1..2147483647>
	*ANY-DISK(...)
		\|	VOLUME = UNCHANGED / [ANY](...) / list-poss(255): <alphanum-name 1..6>
		\|		[*ANY](...)
		\|			\|	NUMBER-OF-DEVICES = 1 / <integer 1..9>
		\|	,DEVICE-TYPE = *UNCHANGED / <device>
		\|	,SPACE = UNCHANGED / RELATIVE(...) / ABSOLUTE(...) / RELEASE(...)
		\|		*RELATIVE(...)
		\|			\|	PRIMARY-ALLOCATION = 0 / <integer 0..2147483647>
		\|			\|	,SECONDARY-ALLOCATION = *UNCHANGED / <integer 0..32767>
		\|		*ABSOLUTE(...)
		\|			\|	FIRST-PAGE = <integer 1..2147483647>
		\|			\|	,SIZE = <integer 1..2147483647>
		\|		*RELEASE(...)
		\|			\|	NUMBER-OF-PAGES = <integer 1..2147483647> / *ALL-RELEASABLE
	*TAPE(...)
		\|	VOLUME = [ANY] (...) / NO / *REMOVE-UNUSED / list-poss(255): <alphanum-name 1..6>
		\|		[*ANY](...)
		\|			\|	NUMBER-OF-DEVICE = 1 / <integer 1..9>
		\|	,DEVICE-TYPE = *UNCHANGED / <device>
		\|	,PREMOUNT-LIST = *NONE / list-poss(255): <integer 0..255>
,DIALOG-CONTROL = STD / NO / ERROR / FILE-CHANGE / *MORE-THAN-ONE-FILE /
							USER-ID-CHANGE / CATALOG-CHANGE
,OUTPUT = NO / SYSOUT

Operands

GENERATION-NAME = <filename 1..54 without-vers with-wild(80)>
Name of an existing file generation. If the generation name includes wildcards, or if the specification is partially qualified, the command is executed for the associated set of files. Processing can be controlled and verified with the aid of the DIALOG-CONTROL and OUTPUT operands. Only systems support personnel (TSOS privilege) is allowed to use wildcards within the user ID.

SUPPORT = *UNCHANGED / *PUBLIC-DISK(...) / *PRIVATE-DISK(...) / *ANY-DISK(...) / *TAPE(...)
Type of volume on which the file generation is located. This entry must not contradict the specification that was made when the catalog entry was created (CREATE-FILE-GENERATION).

SUPPORT = *PUBLIC-DISK(...)
The file generation is located on a public disk.

STORAGE-CLASS = *UNCHANGED / *STD / *UPDATE/ <composed-name 1..8> / *NONE(...)
Governs the properties of the file generation’s storage location. A storage class is a container set up by systems support to hold a defined combination of file attributes specific to an SM pubset. On the basis of the assigned volume set lists it maps these attributes onto the existing range of pubset services. This mapping may be more detailed than can be described by explicitly specifying the IO-ATTRIBUTES, DISK-WRITE, AVAILABILITY, FILE-PREFORMAT, VOLUME-SET, VOLUME, DEVICE-TYPE and S0-MIGRATION operands in the STORAGE-CLASS=*NONE structure.

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]).

At the time when the assignment is made, the storage class that is specified (even implicitly using *STD) must exist, and the user must be authorized to use it. 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.

The WORK-FILE attribute of the storage class must be the same as that of the file generation group.

Defining a different storage class (STORAGE-CLASS not equal *NONE) can result in the file generation being relocated (reallocated) from its current volume set to another volume set which is better suited to this storage class. The following cases can occur here:

If the storage class contains AVAILABILITY=*HIGH and the existing volume set has AVAILABILITY=*STD, the file generation must be reallocated to a volume set with the attribute AVAILABILITY=*HIGH. If reallocation is not possible, the command is rejected.
If the storage class contains a volume set list and the file generation is not located on a volume set of this volume set list, the file generation is, if possible, reallocated to a volume set from this list. If reallocation is not possible, the command is executed without it.

During reallocation, the file generation is open. Accesses from other tasks are rejected.

STORAGE-CLASS = *STD
If the file generation is stored in an SM pubset, it is assigned the default storage class from the group entry of the FGG. The default storage class is governed by the STOR-CLASS-DEFAULT operand of the CREATE-FILE-GROUP or MODIFY-FILE-GROUP-ATTRIBUTES command. If there is no default storage class defined, or if the file generation is stored in an SF pubset, the file generation is given the same attributes as with STORAGE-CLASS= *NONE with default values.

STORAGE-CLASS = *UPDATE
The operand is evaluated only for files in SM pubsets to which a storage class has already been assigned. The attributes are once more read from the storage class catalog and assigned to the file.
The attributes are once more read from the storage class catalog and assigned to the file.

STORAGE-CLASS = <composed-name 1..8>
A file generation in an SM pubset is assigned the specified storage class. If the file generation has already been assigned the specified storage class, the attributes are not updated, so any changes made to the storage class in the intervening period do not come into effect. *UPDATE can be used to ensure that the attributes are updated.
For a file generation in an SF pubset this value has the same effect as STORAGE-CLASS=*NONE with default values.

STORAGE-CLASS = *NONE(...)
The value has the same effect as *UNCHANGED if all the following conditions are fulfilled:

The file generation was or is being created on a volume set for permanent data 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 are the PERFORMANCE, USAGE, DISK-WRITE and AVAILIBILITY operands and the S0-MIGRATION=*ALLOWED specification ignored.

In all other cases, the properties of the file generation’s storage location are determined on the basis of the following operands and no storage class is assigned to the file generation or a storage class which is already assigned is withdrawn.
The properties of the file generation’s storage location are governed by the following operands. The file generation is not assigned a storage class, and any storage class already assigned is disregarded.
See the MODIFY-FILE-ATTRIBUTES command for descriptions of the suboperands

See the MODIFY-FILE-ATTRIBUTES command for descriptions of the other operands.

Return codes

(SC2)	SC1	Maincode	Meaning/Guaranteed messages
	0	CMD0001	Command executed
2	0	DMS051E	Inconsistency in private disk pool or operand error detected
2	0	DMS0546	Catalog entry for specified file has reached maximum size
2	0	DMS054A	Insufficient disk space or access to disk not possible
2	0	DMS06A9	Some generations of this FGG are missing
	1	CMD0202	Syntactical or semantic error in command
	32	DMS05C7	Unexpected internal error in DMS
	32	DMS0584	A state that does not allow the function to continue was reported during processing
	64	CMD0102	Wildcard selection action: processing interrupted by *TERMINATE or by K2 key in verification dialog
	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	DMS0535	Specified file not shareable
	64	DMS0557	Invalid volume specification
	64	DMS055C	Catalog entry not found on specified private disk
	64	DMS057A	Specified storage class not compatible with FGG in terms of WORK-FILE attribute
	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 when processing catalog or multiprocessor system
	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	DMS05A0	Attribute modification not possible - data still in write cache
	64	DMS05BD	Invalid combination of file and volume set attributes
	64	DMS05CC	File name already cataloged
	64	DMS05FC	Specified user ID not in HOME pubset
	64	DMS0681	DMS error on accessing file
	64	DMS0684	File does not exist Guaranteed message: DMS0684
	64	DMS0610	Wildcard selection action: command execution defective for at least one of the selected files
	64	DMS0618	Unknown storage class
	64	DMS061A	Storage class catalog could not be read
	64	DMS0685	File not yet allocated storage space
	64	DMS0689	Operands only allowed for files not yet occupying storage space have been specified
	64	DMS06B5	File already open or catalog entry not updated after system error
	64	DMS06C4	File generation group not yet cataloged
	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
	130	DMS0582	File is currently locked or in use and cannot be processed
	130	DMS0585	Error detected during catalog processing or multihost processing Guaranteed messages: DMS053C
	130	DMS0586	Currently not possible to access or reserve volume
	130	DMS0588	It was not possible to allocate disk space
	130	DMS0594	Not enough virtual memory available
	130	DMS05C8	Maximum permitted number of files reached

Example

Changing the file attributes of a file generation (storage space / primary and secondary allocations)

/show-file-attr max.group.2(*4),inf=(alloc=*yes) —————————————————————————— (1)

%0000000003 :2OSG:$USER1.MAX.GROUP.2(*0004)
%  ------------------------------- ALLOCATION   ------------------------------- 
%  SUPPORT    = PUB         S-ALLOC    = 9           HIGH-US-PA = 0
%  EXTENTS     VOLUME     DEVICE-TYPE      EXTENTS     VOLUME     DEVICE-TYPE
%      1       GVS2.2       D3435
%  NUM-OF-EXT = 1
%:2OSG: PUBLIC:      1 FILE  RES=         3 FRE=         3 REL=         3 PAGES

/mod-file-gen max.group.2(*12), sup=*pub(space=*relative(prim-alloc=90,sec-alloc=30)) ——————— (2)
/show-file-attr max.group.2(*4),inf=(alloc=*yes)———————————————————————————— (3)

%0000000093 :2OSG:$USER1.MAX.GROUP.2(*0004)
%  ------------------------------- ALLOCATION   ------------------------------- 
%  SUPPORT    = PUB         S-ALLOC    = 30          HIGH-US-PA = 0
%  EXTENTS     VOLUME     DEVICE-TYPE      EXTENTS     VOLUME     DEVICE-TYPE
%      2       GVS2.2       D3435
%  NUM-OF-EXT = 2
%:2OSG: PUBLIC:      1 FILE  RES=        93 FRE=        93 REL=        93 PAGES

(1)	The SHOW-FILE-ATTRIBUTES command indicates that three PAM pages are reserved (initial allocation) for the file MAX.GROUP.2(4)*.
(2)	The MODIFY-FILE-GENERATION-SUPPORT command raises the primary space allocation by 90 PAM pages and sets the secondary space allocation to 30 PAM pages (for subsequent storage space extensions).
(3)	The SHOW-FILE-ATTRIBUTES command indicates the new number of reserved pages (93) and the new secondary allocation (30).

Your Browser is not longer supported

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

MODIFY-FILE-GENERATION-SUPPORT