ERASE - Erase files

Macro type: type S (E form/L form/D form); see "Macro types"

Using the ERASE macro, the user can erase his/her own temporary or permanent files, file generation groups or file generations, depending on the selection criteria specified in the command. Furthermore, the user can release storage space and export files (= delete their catalog entries). The operands of the ERASE macro can be divided into five groups which correspond to the various functional levels (see table).

Selection operands

By means of the selection operands, the user specifies which files or catalog entries are to be processed, using attributes stored in the catalog entries as selection criteria. For this purpose, some operands of the FSTAT macro are integrated in the ERASE macro.If a selection operand is omitted, the files/catalog entries to be processed are selected without taking that selection criterion into account.

File protection operands

File protection operands make it unnecessary for the user to reset the protection attributes in order to erase files for which file protection attributes such as passwords, retention period, etc. are defined.

Macro execution

Action operands control the internal execution of the ERASE macro. The user can specify the scope for erasure and also define conditions for erasure.

Control operands permit the user to define, to a certain degree, his/her own user interface. (S)he can, for example, have a log printed or respond to control questions in a dialog.

Macro generation

Assembler operands control how the macro is generated. The VERSION operand, for example, controls the generation of the operand list.

Source compatibility is ensured for existing programs since the new format VERSION=3 fully covers the functions of the old formats VERSION=0/1/2. The only exception to this is: if the generated operand list is modified in the program, the program must be re-assembled.

Functional overview

Operand	Operand value	Selection criterion
Selection – file name
*DUMMY		Dummy file
pathname		Path name (fully qualified, partially qualified, wildcards)
prefix		Temporary user files
*SYSid		System files, wildcards permitted
*		EAM object module file
Selection – file type
BLKCTRL	NONE PAMKEY/DATA/DATA2K/ DATA4K/NO/NK/NK2/NK4	Catalog entries of unopened files File format
FCBTYPE	NONE ISAM/SAM/BTAM/PAM	Catalog entries of unopened files Access method
FILTYPE	*ANY/*BS2000/*NODE	File type on Net-Storage: BS2000 file or node file
POS	AFTER/BEFORE	In conjunction with TYPE=FGG; specifies the file generations to be processed
TYPE	FILE FGG PLAM	Files, not FGGs or file generations File generations or FGGs PLAM libraries
WORKFIL	*NO/*YES	Work files
Selection – volume
STOTYPE	*PUBSPACE/*NETSTOR	Storage type
SUPPORT	PUBLIC PRDISC TAPE	Files on public disks Files on private disks Tape files
VOLSET		Volume set
VOLUME		VSN of the volume
Selection – data security and protection
ACCESS	READ/WRITE	Write protection
AVAIL	*STD/*HIGH	Availability
BACKUP	A/B/C/D/E	Backup level
BASACL	NONE/YES	BASIC-ACL protection
ENCRYPT	ANY/NONE/AES/DES	Encrypted files
GROUPAR	NO-ACCESS/access-list	Access rights of the user group
GUARDS	(READ...,WRITE...,EXEC...)	GUARDS protection
OTHERAR	NO-ACCESS/access-list	Access rights of the others group
OWNERAR	NO-ACCESS/access-list	Access rights of the owner
PASS	NONE EXPASS RDPASS WRPASS	Password protection
PROTACT	ANY/LEVEL-0/ LEVEL-1/LEVEL-2	Protection level of the activated access control method
SHARE	NO/YES/SPECIAL	Shareability
Selection – storage space (disk files)
EXTENTS		Number of extents
FSIZE		Size of reserved but unused storage space
LASTPAG		Number of PAM pages used
RELSPAC		Lock preventing release of storage space
SIZE		Size of reserved storage space
Selection – storage space (tape files)
BLKCNT		Number of blocks in the file on tape
Selection – date and time entries
CRDATE		Date and time of creation
DELDATE		DELETION date and time (implicit: retention period)
EXDATE		Expiration date and time (implicit: retention period)
LADATE		Date and time of last access
LCDATE		Date and time of last write access
TIMBASE	*UTC/*LTI	Time base of date entries
Selection – HSMS
MIGRATE	ALLOWED/ INHIBIT/ FORBIDDEN	Migration allowed/ briefly allowed/ not allowed
SLEVEL	S0/S1/S2	Storage level
S0MIGR	*ALLOWED/*FORBIDDEN	Migration allowance
Selection – performance and I/O attributes
DISKWR	IMMEDIATE/BY-CLOSE	Time at which data is written back to disk
IOPERF	STD/HIGH/VERY-HIGH	Performance attribute
IOUSAGE	RDWRT/WRITE/READ	Type of I/O operation
Selection – file status
STATE	NOCLOS CLOSED CACHED NOT-CACHED CACHE-NOT-SAVED REPAIR-NEEDED DEFECT-REPORTED OPEN-ALLOWED NO-OPEN-ALLOWED	Current status of the file
Selection – coding
CCS		Code table (coded character set)
Selection – metainformation
ADMINFO	*NONE/<c-string 1..8>	System administrator metainformation
USRINFO	*NONE/<c-string 1..8>	User metainformation
Selection – SM pubset
MANCLAS	*NONE/<c-string 1..8>	Management class
PREFORM		Intended file format on SM pubsets
STOCLAS	*NONE/<c-string 1..8>	Storage class
File protection – file protection operands
IGNORE	omitted	Defined protection attributes are evaluated
	ACCESS	The protection attribute ACCESS=READ, BASIC-ACL or GUARDS is ignored
	EXDATE	Retention periods are ignored
	RDPASS WRPASS EXPASS	For system administration only: Dialog for change of user ID
PASSWORD	omitted password	Password protection is evaluated The password protection defined by the specified password is ignored
Macro execution – action operands
CATALOG		Files on private volumes are exported
DATA		Logical erasure: the data-specific attributes of the file are deleted, the catalog entry updated accordingly and the allocated storage space is retained
DATA-KEEP- ATTR		Logical erasure as with DATA, but the data-specific attributes are retained
DELETE-OR- EXPORT		Files on private volumes and node files on Net-Storage volumes are exported, files on public disks or on Net-Storage volumes are deleted
DESTROY		The catalog entry is deleted, the storage space is released and overwritten
MOUNT		Specifies, for files on private disks, whether all affected disks must be online
SPACE		Only storage space is released, the catalog entry is retained
SPACE- CATALOG		The catalog entry is deleted and storage space released
Macro execution – control operands
CHECK	NO	No user intervention permitted (default value for procedures and batch jobs)
	MULTIPLE	Dialog when the catalog or user ID is changed if “pathname” was not fully qualified (default value for interactive mode)
	ERROR	Dialog if a user-correctable error occurs
	PVS	Dialog when the catalog ID is changed
	SINGLE	The user decides, in a dialog, whether each selected file is to be processed by the current ERASE macro
	USERID	For system administration only: Dialog for change of user ID
LIST	NO/YES	[Do not] log erasure on SYSOUT
NOSTEP	errcode	Via the DMS error code, the user can specify which errors are not to trigger the spin-off mechanism
Macro generation – assembler operands
MF		Macro generation (operand list/SVC/DSECT)
PREFIX	prefix	Call-specific prefix
VERSION	0	Macro format for BS2000 versions < V9.5A (see table "Variations in versions - VERSION=0/1/2")
VERSION	1	Macro format for BS2000 Versions V9.5A and V10.0A (see table "Variations in versions - VERSION=0/1/2")
VERSION	2	Macro format as of BS2000/OSD-BC V1.0 (see “Macro format and operand descriptions” below)
VERSION	3	Macro format as of BS2000/OSD-BC V3.0 (see “Macro format and operand descriptions” below)

Operand overview

Operand	Operand value	Function
*DUMMY		Selection operand dummy file
pathname		Selection operand - path name (fully qualified, partially qualified, wildcards)
prefix		Selection operand - temporary user files
*SYSid		Selection operand - system files, wildcards permitted
*		Selection operand - EAM object module file
CATALOG		Files on private volumes are exported
DATA		Logical erasure: the data-specific attributes of the file are deleted, the catalog entry updated accordingly and the allocated storage space is retained
DATA-KEEP- ATTR		Logical erasure as with DATA, but the data-specific attributes are retained
DELETE-OR- EXPORT		Files on private volumes and node files on Net-Storage volumes are exported, files on public disks or on Net-Storage volumes are deleted
DESTROY		The catalog entry is deleted, the storage space is released and overwritten
MOUNT		Specifies, for files on private disks, whether all affected disks must be online
SPACE		Only storage space is released, catalog entry is retained
SPACE- CATALOG		The catalog entry is deleted and storage space released
ACCCNT		Selection operand - access counter
ACCESS	READ/WRITE	Selection operand - write protection
ADMINFO	*NONE/ <c-string 1..8>	Selection operand - system administrator metainformation
AVAIL	*STD/*HIGH	Selection operand - availability
BACKUP	A/B/C/D/E	Selection operand - backup level
BASACL	NONE/YES	Selection operand - BASIC-ACL protection
BLKCNT		Selection operand - number of blocks in the file on tape
BLKCTRL	NONE PAMKEY/DATA/ DATA2K/DATA4K/ NO/NK/NK2/NK4	Selection operand - catalog entries of unopened files File format
CCS		Selection operand - code table (coded character set)
CHECK	NO	No user intervention permitted (default value for procedures and batch jobs)
	MULTIPLE	Dialog when the catalog or user ID is changed if “pathname” was not fully qualified (default value for interactive mode)
	ERROR	Dialog if a user-correctable error occurs
	PVS	Dialog when the catalog ID is changed
	SINGLE	The user decides, in a dialog, whether each selected file is to be processed by the current ERASE macro
	USERID	For system administration only: dialog for change of user ID
CRDATE		Selection operand - date and time of creation
DELDATE		Selection operand - DELETION date and time (implicit: retention period)
DISKWR	IMMEDIATE/ BY-CLOSE	Selection operand - time at which data is written back to disk
EXDATE		Selection operand - expiration date and time (implicit: retention period)
EXTENTS		Selection operand - number of extents
FCBTYPE	NONE ISAM/SAM/ BTAM/PAM	Selection operand - catalog entries of unopened files Access method
FILTYPE	*ANY/*BS2000/ *NODE	Selection operand – file type on Net-Storage (BS2000 file or node file)
FSIZE		Selection operand - size of reserved but unused storage space
GROUPAR	NO-ACCESS/ access-list	Selection operand - access rights of the user group
GUARDS	(READ..., WRITE..., EXEC...)	Selection operand - GUARDS protection
IGNORE	omitted	Defined protection attributes are evaluated
	ACCESS	The protection attribute ACCESS=READ, BASIC-ACL or GUARDS is ignored
	EXDATE	Retention periods are ignored
	RDPASS WRPASS EXPASS	For system administration only: the defined password is ignored
IOPERF	STD/HIGH/ VERY-HIGH	Selection operand - performance attribute
IOUSAGE	RDWRT/WRITE/ READ	Selection operand - type of I/O operation
LADATE		Selection operand - date and time of last access
LASTPAG		Selection operand - number of PAM pages used
LCDATE		Selection operand - date and time of last write access
LIST	NO/YES	[Do not] log erasure on SYSOUT
MANCLAS	*NONE/ <c-string 1..8>	Selection operand - management class
MF		Macro generation (operand list/SVC/DSECT)
MIGRATE	ALLOWED/ INHIBIT/ FORBIDDEN	Selection operand - migration allowed/ briefly allowed/ not allowed
NOSTEP	errcode	Via the DMS error code, the user can specify which errors are not to trigger the spin-off mechanism
OTHERAR	NO-ACCESS/ access-list	Selection operand - access rights of the others group
OWNERAR	NO-ACCESS/ access-list	Selection operand - access rights of the owner
PASS	NONE EXPASS RDPASS WRPASS	Selection operand - password protection
PASSWORD	omitted password	Password protection is evaluated The password protection defined by the specified password is ignored
POS	AFTER/BEFORE	Selection operand - in conjunction with TYPE=FGG; specifies the file generations to be processed
PREFIX	prefix	Call-specific prefix
PREFORM		Selection operand - intended file format on SM pubsets
PROTACT	ANY/LEVEL-0/ LEVEL-1/LEVEL-2	Selection operand - protection level of the activated access control method
RELSPAC		Selection operand - lock preventing release of storage space
SHARE	NO/YES/SPECIAL	Selection operand - shareability
SIZE		Selection operand - size of reserved storage space
SLEVEL	S0/S1/S2	Selection operand - storage level
STATE	NOCLOS CLOSED CACHED NOT-CACHED CACHE-NOT-SAVED REPAIR-NEEDED DEFECT-REPORTED OPEN-ALLOWED NO-OPEN-ALLOWED	Selection operand - current status of the file
STOCLAS	*NONE/ <c-string 1..8>	Selection operand - storage class
STOTYPE	*PUBSPACE/ *NETSTOR	Selection operand - storage type
SUPPORT	PUBLIC PRDISC TAPE	Selection operand - files on public disk Files on private disk Tape volume
S0MIGR	*ALLOWED/ *FORBIDDEN	Selection operand - migration allowance
TIMBASE	*UTC/*LTI	Selection operand - time base of date entries
TYPE	FILE FGG PLAM	Selection operand - files, not FGGs or file generations File generations or FGGs PLAM libraries
USRINFO	*NONE/ <c-string 1..8>	Selection operand - user metainformation
VERSION	0	Macro format for BS2000 versions < V9.5A (see table "Variations in versions - VERSION=0/1/2")
	1	Macro format for BS2000 versions V9.5A and V10.0A (see table "Variations in versions - VERSION=0/1/2")
	2	Macro format as of BS2000/OSD-BC V1.0 (see Macro format and operand descriptions)
	3	Macro format as of BS2000/OSD-BC V3.0 (see Macro format and operand descriptions)
VOLSET		Selection operand - volume set
VOLUME		Selection operand - VSN of the volume
WORKFIL	*NO/*YES	Selection operand - work files

Format

The macro format represented below contains all the operands that are supported as of BS2000/OSD-BC V3.0. In order to generate this format, VERSION=3 must be specified.

Source code compatibility for existing programs is ensured, since the new format VERSION=3 completely covers the functions of the old formats VERSION=0/1/2. However, an operand list generated in the program can only be changed if the program is reassembled with the updated macro.

• All operands/operand values that were supported up to and including BS2000 Version V2.0A may be used in the macro format with VERSION=2.

• All operands/operand values that were supported up to and including BS2000 Version V10.0A may be used in the macro format with VERSION=1.

• Operands/operand values that were supported up to and including BS2000 Version V9.0A may be used in the macro format with VERSION=0.

The table "Variations in versions - VERSION=0/1/2" shows which operands/operand values are supported with VERSION=2/1/0.

In the format, the representation of operands for which a list of operand values can be specified has been simplified. The list is shown as an additional value (list-of-operand) in the format and should be interpreted as follows:

• several operand values can be specified in the form of a list:
  (element1, element2, ...)

• if only one operand value is specified, i.e. the list consists of only one element, the parentheses may be omitted: element or (element). 

Operation	Operands
ERASE	[pathname / prefix / * / *SYSid / *DUMMY] [,SPACE-CATALOG / SPACE / DATA / DATA-KEEP-ATTR / CATALOG /   DELETE-OR-EXPORT / DESTROY] [,ACCCNT = ANY / nmbr / (nmbr[,]) / (,nmbr) / (nmbr1,nmbr2) [,ACCESS = ANY / READ / WRITE] [,ADMINFO = *ANY / *NONE / <c-string 1..8>] [,AVAIL = *ANY / *STD / *HIGH] [,BACKUP = ANY / A / B / C / D / E / (list-of-backup)] [,BASACL = ANY / NONE / YES] [,BLKCNT = ANY / nmbr / (nmbr[,]) / (,nmbr) / (nmbr1,nmbr2)] [,BLKCTRL = ANY / PAMKEY / DATA4K / DATA2K / DATA /             NO / NONE / NK4 / NK2 / (list-of-blkctrl)] [,CCS = *ANY / *NONE / ccs-name] [,CHECK = NO / STD / MULTIPLE / ERROR / PVS / SINGLE / USERID] [,CRDATE = *ANY / *NONE / date / date(time[,]) / date(time1,time2) /            (date[,]) / (date(time)[,]) / (,date) / (,date(time)) /            (date1,date2) / (date1(time),date2) /            (date1(time),date2(time))] [,DELDATE = *ANY / *NONE / date / date(time[,]) / date(time1,time2) /             (date[,]) / (date(time)[,]) / (,date) / (,date(time)) /             (date1,date2) / (date1(time),date2) /             (date1(time),date2(time))] [,DISKWR = ANY / IMMEDIATE / BY-CLOSE] [,ENCRYPT = *ANY / *NONE / *AES / *DES / (list-of-encrypt)] [,EXDATE = *ANY / *NONE / date / date(time[,]) / date(time1,time2) /            (date[,]) / (date(time)[,]) / (,date) / (,date(time)) /            (date1,date2) / (date1(time),date2) /            (date1(time),date2(time))] [,EXTENTS = ANY / nmbr / (nmbr[,]) / (nmbr1,nmbr2)] [,FCBTYPE = ANY / ISAM / BTAM / SAM / PAM / NONE / (list-of-fcbtype)] [,FILTYPE = *ANY / *BS2000 / *NODE] [,FSIZE = ANY / SIZE / nmbr / (nmbr[,]) / (nmbr) / (nmbr1,nmbr2)] [,GROUPAR = ANY / NO-ACCESS / list-of-ownerar] [,GUARDS = *ANY /            *NONE /            *YES /            ([READ = *ANY / *NONE / fname]             [,WRITE = *ANY / *NONE / fname]             [,EXEC = *ANY / *NONE / fname])] [,IGNORE = ANY / ACCESS / EXDATE / RDPASS / WRPASS / EXPASS /            (list-of-ignore)] [,IOPERF = ANY / STD / HIGH / VERY-HIGH / (list-of-ioperf)] [,IOUSAGE = ANY / RDWRT / WRITE / READ / (list-of-iousage)] [,LADATE = *ANY / *NONE / date / date(time[,]) / date(time1,time2) /            (date[,]) / (date(time)[,]) / (,date) / (,date(time)) /            (date1,date2) / (date1(time),date2) /            (date1(time),date2(time))] [,LASTPAG = ANY / nmbr / (nmbr[,]) / (,nmbr) / (nmbr1,nmbr2)] [,LCDATE = *ANY / *NONE / date / date(time[,]) / date(time1,time2) /            (date[,]) / (date(time)[,]) / (,date) / (,date(time)) /            (date1,date2) / (date1(time),date2) /            (date1(time),date2(time))] [,LIST = ERRORS-TO-SYSOUT / (area,len)] [,MANCLAS = *ANY / *NONE / <c-string 1..8>] [,MIGRATE = ANY / ALLOWED / INHIBIT / FORBIDDEN / (list-of-migrate)] [,MOUNT = FIRST-DISK / ALL-DISKS] [,NOSTEP = errcode / (list-of-nostep)] [,OTHERAR = ANY / NO-ACCESS / list-of-ownerar] [,OWNERAR = ANY / NO-ACCESS / list-of-ownerar] [,PASS = ANY / NONE / EXPASS / RDPASS / WRPASS / (list-of-pass)] [,PASSWD = kennwort / (list-of-passwd)] [,POS = AFTER / BEFORE] [,PREFORM = *ANY / *NONE / *K / *NK2 / *NK4 / (list-of-preform)] [,PROTACT = ANY / LEVEL-0 / LEVEL-1 / LEVEL-2 / (list-of-protact)] [,RELSPAC = ANY / ALLOWED / IGNORED / (list-of-relspac)] [,SHARE = ANY / YES / NO / SPECIAL / (list-of-share)] [,SIZE = ANY / FSIZE / nmbr / (nmbr[,]) / (,nmbr) / (nmbr1,nmbr2)] [,SLEVEL = ANY / S0 / S1 / S2 / (list-of-slevel)] [,STATE = ANY / NOCLOS / CLOSED / CACHED / NOT-CACHED / CACHE-NOT-SAVED /           OPEN-ALLOWED / NO-OPEN-ALLOWED / REPAIR-NEEDED /           DEFECT-REPORTED / (list-of-state)] [,STOCLAS = *ANY / *NONE / <c-string 1..8>] [,STOTYPE = *ANY / *PUBSPACE / *NETSTOR] [,SUPPORT = ANY / PUBLIC / PRDISC / TAPE / (list-of-support)] [,S0MIGR = *ANY / *ALLOWED / *FORBIDDEN / (list-of-s0migr)] [,TIMBASE = *UTC / *LTI] [,TYPE = ANY / FILE / FGG / PLAM / (list-of-type)] [,USRINFO = *ANY / *NONE / <c-string 1..8>] [,VOLSET = *ANY / <c-string 1..4>] [,VOLUME = *ANY / vsn] [,WORKFIL = *ANY / *NO / *YES]
	[,MF = L],VERSION = 0 / 1 / 2 / 3[,PREFIX = pre]
	MF = (E,adr / E,(r)),VERSION = 0 / 1 / 2 / 3
	MF = D,VERSION = 1 / 2 / 3[,PREFIX = pre]

Operand descriptions

pathname

Designates the pathname of the files that are to be erased, with:
<c-string 1..80: filename 1..54 with-wild(80) without-gen>

Only the user's own files or for which the user possesses co-owner rights may be erased.

pathname means [:catid:][$userid.][filename]

catid
Catalog ID of the files that are to be erased; if wildcards are used for “catid”, then these are evaluated only for catalogs in an MPVS environment. Catalogs in an MSCF environment can be addressed only via their explicit “catid” (for information on MSCF see the “HIPLEX MSCF” User Guide [11]).
The default value is the “catid” assigned to the user ID.

userid
User ID: non-privileged users may only delete their own files or files under user IDs for which they are entered as co-owner. The system administrator can also specify wildcards.
Default value: the user ID of the current job (i.e. of the SET-LOGON-PARAMETERS or LOGON command).

filename
Designates the files, file generations, FGGs or temporary files to be erased. The user may specify a fully or partially qualified file name or use wildcards. The prefix must be included in the names of temporary files; otherwise, the temporary files are ignored.

Wildcard specifications
Nonprivileged users may only use wildcards in the “catid” and “filename” specifications whereas the system administrator may also use them in the “userid” (as in the FSTAT macro; see section "Wildcards"). If the wildcard '*' is used, it must be entered twice (**) if it is to include the beginning of the file name (for example: ERASE *SYSLST erases the system file SYSLST, while ERASE **SYSLST erases all files whose names end with the string SYSLST).

prefix

With the prefix defined for temporary files, all temporary files of the job can be erased. If the erase operation is logged, the internal names of the temporary files being processed are output.

*
The ERASE macro is for the EAM object module file (* file) which is created and used by compilers. All operands except the control and Assembler operands (CHECK, LIST, NOSTEP) are checked for syntax errors, but are otherwise ignored. Errors which occur when erasing the * file are ignored.

*SYSid
Designates the logical system files SYSLST, SYSLSTnn and SYSOUT (00 <= nn <= 99). Wildcards may be specified for “id”, which means that one ERASE command may be used for several system files (see section "Wildcards" for details of wildcards). All operands except the control operands (CHECK, LIST, NOSTEP) are checked for syntax errors, but are otherwise ignored.

The system file SYSOUT can also be erased in dialog mode.

If SYSLST is assigned to a file and has been printed out with PRINT *SYSLST, a subsequent ERASE *SYSLST macro logically erases only those pages which have been created since the printout.

If a LOGOFF command immediately follows an ERASE *SYSOUT or ERASE *SYSLST and no log is requested via LIST=YES or /OPTION MSG=H, no new SYSOUT or SYSLST file is created.

*DUMMY
Designates the dummy file *DUMMY, which “always exists” and fulfills all selection criteria. All operands except the control operands (CHECK, LIST, NOSTEP) are checked for syntax errors, but are otherwise ignored. If *DUMMY is specified, no catalog or data access is necessary. *DUMMY is particularly useful for test runs.

CATALOG

Only for files, file generation groups and file generations on private volumes and for files on Net-Storage of type NETSTOR:
The catalog entries of the specified or selected files are deleted, but their storage space is retained. Password protection is observed, but write protection defined with ACCESS=READ or implied by RETPD (see the CATAL macro) is ignored. Any definition for “binary deletion” (see DESTROY, CATAL macro) in the catalog entry is also ignored.

For tape files, “CATALOG” is the default value for the execution of ERASE.

The action ERASE ...,CATALOG is equivalent to exporting the file(s) (see the VOLUME operand). These files can be imported again later, either individually by means of FILE (with STATE=FOREIGN) or using IMPORT, which can import one or more files on private disks or on Net-Storage of type NETSTOR at the same time. Exclusively reserved files cannot be exported.

Files on a Net-Storage volume of type NETVOL cannot be exported, because there is no file catalog (BS2FSCAT) on the Net-Storage volume.

DATA

Only for disk files; the default value CATALOG applies to tape files:
The data of the affected files is “logically erased” (see “Logically erasing a file” in the ”Introductory Guide to DMS” [1]). After this, the user can no longer access the file’s data since physical access to the relevant volume is not permitted. The catalog entry and the space allocation still exist. The catalog entry is identical to that for a file which has been created by means of FILE but not yet opened (FCBTYPE=NONE, CRDATE=NONE).

DATA-KEEP-ATTR

Only for disk files; the default CATALOG applies for tape files:
The files are logically erased as with DATA, but the data-specific attributes are retained. The data itself can, however, no longer be addressed by the user.

DELETE-OR-EXPORT

Selects files for processing by ERASE on the basis of the type of volume on which the files are stored:

• Files, FGGs, etc. on public volumes and files are erased, i.e. the catalog entry is deleted and the storage space is released (corresponds to the specification “SPACE-CATALOG”).

• For files on Net-Storage the following applies depending on the file type:

  • For BS2000 files the catalog entry is deleted and the storage space is released, regardless of the Net-Storage volume type (NETSTOR or NETVOL) on which they reside.

  • For node files the catalog entry is deleted. The files are retained on the Net-Storage (corresponds to the EXPORT-NODE-FILE command),regardless of the Net-Storage volume type (NETSTOR or NETVOL) on which they reside.

• For files, FGGs, etc. on private volumes, the catalog entry is simply deleted (corresponds to the specification “CATALOG”).

DESTROY

Only for disk files; the default value CATALOG is valid for tape files:
The storage space for the selected files is released, the catalog entry is deleted, and the storage space being released is overwritten by binary zeros so that if the space is allocated again, nobody can read the old data (data protection). In the case of files on private disks, all volumes on which the file was stored must be mounted when erasure takes place.

“Data destruction” during erasure can also be set in the catalog entry (DESTROY=YES) by means of the CATAL macro. In this case, the storage space being released is automatically overwritten. When a file is erased, the action operands are evaluated first: if the file is to be exported (specification CATALOG or DELETE-OR-EXPORT), the data is not overwritten, since the storage space is not released.

SPACE

Only for files on public disks and on Net-Storage; the default value CATALOG is valid for tape files:
The storage space for the files affected by ERASE is released. The catalog entry is retained but updated: it is then identical to one created via CATAL. The SPACE operand is rejected for files on private disks.

SPACE-CATALOG

is the default value for disk files; the catalog entries for the affected files are deleted, and the storage space used by these files is released. 

ACCCNT

Allows the user to select files to be processed on the basis of the access count, which indicates how often a file has been accessed. The access counter can be assigned values from 0 to 2147483647.

= ANY
The access counter is not a selection criterion.

= nmbr
Processes files for which the access count exactly matches the specified number of accesses.

= (nmbr[,])
Processes files for which the access count is greater than or equal to the specified value.

= (,nmbr)
Processes files for which the access count is less than or equal to the specified value.

= (nmbr1,nmbr2)
Processes files for which the access count lies in the specified interval:(nmbr1 <= access-count <= nmbr2).

ACCESS

The user can select files for processing depending on his or her access authorization.

= ANY
The access type is not a selection criterion.

= READ
Only files for which write access is forbidden by ACCESS=READ, i.e. read-only files, are processed.

= WRITE
Selects files for which read and write access is permitted.

ADMINFO

The user can select files/file generations for processing dependent on the system administrator metainformation.

= *ANY
The system administrator metainformation is not a selection criterion.

= *NONE
Only those files are processed that possess no system administrator metainformation.

= <c-string 1..8>
Only those files possessing the specified system administrator metainformation are processed.

AVAIL

The user can select files/file generations for processing dependent on their availability.

= *ANY
The availability is not a selection criterion.

= *STD
Only those files not on a volume set with high availability are processed.

= *HIGH
Only those files on a volume set with high availability are processed (DRV pubset).

BACKUP

The user can select the files for processing on the basis of the BACKUP level. The backup defines in which backup runs the file is to be saved.

= ANY
The backup level is not a selection criterion.

= A
Only the files with backup level A are processed.

= B
Only the files with backup level B are processed.

= C
Only the files with backup level C are processed.

= D
Only the files with backup level D are processed.

= E
Only the files with backup level E are processed.

= (list-of-backup)
All files that have one of the specified backup levels are processed. Up to 5 backup different levels may be specified in a list.

BASACL

Allows the user to select files for processing on the basis of whether they are protected by a basic access control list (BASIC-ACL).

= ANY
The BASIC-ACL is not a selection criterion.

= NONE
Processes all files for which no BASIC-ACL entry is defined.

= YES
Processes only those files for which a BASIC-ACL entry is defined. The selection operands OWNERAR, GROUPAR, and OTHERAR can be used to restrict the selection to specific BASIC-ACL entries.

BLKCNT

For tape files only:
Selects files for processing on the basis of the number of blocks on tape.

= ANY
The number of blocks on tape is not a selection criterion.

= nmbr
Processes all tape files with exactly the specified number of blocks.

= (nmbr[,])
Processes all tape files for which the number of blocks is greater than or equal to the specified value.

= (,nmbr)
Processes all tape files for which the number of blocks is less than or equal to the specified value.

= (nmbr1,nmbr2)
Processes all tape files for which the number of blocks lies within the specified interval.

Any integers from the range 0 <= value <= 2147483647 may be specified.

BLKCTRL

Allows the user to select files for processing on the basis of the file format. The file format is defined when creating the file and is based on the existence and position of the block control field that contains management information for the PAM page.

= ANY
The file format is not a selection criterion.

= PAMKEY
Processes all files which use a separate PAM key for the block control field, i.e. files for which the block control information is stored in a special key field outside the PAM block. Such files are created with BLKCTRL=PAMKEY (see the FILE macro).

= DATA
Processes all files for which the block control information is located at the start of the data block. Such files are created with BLKCTRL=DATA (see the FILE macro).

= NO
Processes all files which contain no block control field. Such files are created with BLKCTRL=NO (see the FILE macro).

= NONE
Processes all files for which no BLKCTRL value was defined, i.e. files which have not yet been opened.

= DATA2K
Processes all files which were created with BLKCTRL=DATA2K (see the FILE macro).

= DATA4K
Processes all files that were created with BLKCTRL=DATA4K (see the FILE macro).

= NK2
Processes all NK2 files (files which can be stored on NK2 volumes).

= NK4
Processes NK4 files only (files which can be stored on NK4 volumes).

= (list-of-blkctrl)
Processes all files that match one of the specified file formats. All values except ANY may be specified in a list. 

CCS

Allows the user to select files for processing on the basis of the specified coded character set.
The coded character set (CCS) defines how the characters of a national character set are to be stored in binary form. The specified character set has an effect on the representation of characters on the screen, the collating sequence, etc. (see the “XHCS” manual [22]).

= *ANY
The code table is not a selection criterion for files to be processed with ERASE.

= *NONE
Only files for which no character set is defined are erased.

= ccs-name
Only the files for which the specified code table was defined are processed. The name of the code table may consist of up to 8 alphanumeric characters.

CHECK

As in interactive mode, the user can specify that a control check be performed by issuing a prompt to SYSOUT before a file set is processed. The file set for which the prompted dialog is to be executed can be specified by the user (e.g. for all files to be processed). The issued prompt must be answered by the user as follows:

• “Y” confirms that the specified file set is to be processed.

• “N” excludes the specified file set from the operation.

• “T” terminates the entire ERASE processing operation.

Any response that consists of only blanks or the “null string” will be interpreted as “N”.

In batch mode, CHECK=NO always applies.

= STD
The default setting depends on the operating mode:

• • • In an interactive dialog (SYSCMD is assigned to the terminal), CHECK=MULTIPLE is the default.

    • In procedures and in batch mode, the default value is CHECK=NO.

= NO
The user cannot intervene in the ERASE processing; all specified or selected files are erased.

= MULTIPLE
If “pathname” is partially qualified, which means that more than one file is selected, or if “pathname” contains wildcards, the user can decide, each time the catalog ID changes, whether or not files from the new catalog are to be erased. He/she must respond with “YES” or “NO” to the question issued by the system. CHECK=MULTIPLE

is useful if wildcards are specified for “catid” in the “pathname”. In the dialog, ERASE processing can be terminated by responding with “TERMINATE” to the question, or the CHECK mode can be changed
( -> NO/ERROR/SINGLE/PVS).

= ERROR
By means of CHECK=ERROR, the user specifies that a dialog as for CHECK=SINGLE is to be started if user-correctable errors occur. As long as no errors occur, CHECK=ERROR is equivalent to CHECK=NO (i.e. no dialog). CHECK=ERROR is set implicitly if CHECK=SINGLE is selected.

In the case of an error, the user can acknowledge the error message, abort ERASE processing or attempt to recover the error. If desired, he/she can also change the CHECK mode.

= PVS
As for CHECK=MULTIPLE, ERASE processing starts a dialog if files in different catalogs are affected by the ERASE macro. The user can respond with “YES” or “NO” to the system question, abort ERASE processing (“TERMINATE”) or change the CHECK mode.

= SINGLE
For each file which is processed, the user can decide in a dialog whether or not it is to be erased (response YES/NO). If, in the dialog, (s)he specifies protection attributes or one or more passwords together with “IGNORE”, these specifications are evaluated and any file which fulfills them is erased without further questions (“YES” must also be specified). The user can also abort ERASE processing or change the CHECK mode.

The affected files are listed in alphabetical order. If file generation groups are affected, the generations are listed separately in the order of their generation numbers. If the user elects not to erase a file generation, processing of the file generation group is terminated and the current status is saved (there must be no gaps in the sequence of file generations).

If only parts of a generation group are to be erased, the order of the generations depends on the value of the POS operand: with POS=AFTER, the generations are listed in descending order of their generation numbers, starting with the youngest generation; with POS=BEFORE, they are listed in ascending order of their generation numbers, starting with the oldest generation.

= USERID
For system administration only:
ERASE processing branches to an interactive dialog if files of various user IDs are involved. Whenever the user ID changes, a prompt is issued to determine whether the next user ID is to be processed.
The system administrator can accept (“YES”), deny (“NO”), or end (“TERMINATE”) the ERASE operation, or switch to CHECK mode.

CRDATE

Allows the user to select files for processing on the basis of their creation dates. File generation groups and file generations are not taken into account.

Date values may be supplemented by specifying a time. The rules for date and time specifications are described on "Format of date specifications". Range specifications are inclusive of both specified limits.

= ANY
The creation date is not a selection criterion.

= NONE
Processes all files for which no creation date has been entered in the catalog, i.e. files which have not yet been opened.

= date
Processes all files that were created on the specified date.

= (date[,])
Processes all files that were created on or after the specified date
(creation date >= current date).

= (,date)
Processes all files that were created on or before the specified date
(creation date <= current date).

= (date1,date2)
Processes all files that were created within the specified period
(date1 <= creation date <= date2).

= date(time[,])
Processes all files that were created on the specified date on or after the specified time.

= date(time1,time2)
Processes all files that were created on the specified date within the specified period.

= (date(time)[,])
Processes all files that were created on or after the specified date and time.

= (,date(time))
Processes all files that were created before the specified date and time.

(date1(time),date2(time))
Processes all files that were created within the specified period. The upper and lower limits of the specified period are defined more precisely by a time specification in both cases.

DELDATE

Allows the user to select files on the basis of the DELETION-DATE (the time from which the file may be deleted irrespective of the protection attributes).

The user can supplement the date values by specifying a time. It must be noted in this respect that the deletion time of 00:00:00 is currently always entered in the file catalog.

The rules for date and time specifications are described on "Format of date specifications". Range specifications are inclusive of both specified limits.

= *ANY
The DELETION-DATE is not a selection criterion.

= *NONE
Processes all files for which no DELETION-DATE is entered in the catalog.

= date
Processes all files for which the specified DELETION-DATE is defined.

= (date[,])
Processes all files whose DELETION-DATE is later or equal to the specified date.

= (,date)
Processes all files whose DELETION-DATE is earlier or equal to the specified date.

= (date1,date2)
Processes all files whose DELETION-DATE lies within the specified time period
(date1 <= release date <= date2). 

= date(time[,])
Processes all files for which the specified DELETION-DATE is defined and for which the release time is later or equal to the specified time. The release time (referred to the DELETION-DATE) is always entered in the catalog as 00:00:00.

= date(time1,time2)
Processes all files for which the specified DELETION-DATE is defined and for which the release time is within the specified time period. The release time (referred to the DELETION-DATE) is always entered in the catalog as 00:00:00.

= (date(time)[,])
Processes all files whose DELETION-DATE and time is later than or equal to the specified time. The release time (referred to the DELETION-DATE) is always entered in the catalog as 00:00:00.

= (,date(time))
Processes all files whose DELETION-DATE and time is earlier than or equal to the specified time. The release time (referred to the DELETION-DATE) is always entered in the catalog as 00:00:00.

(date1(time),date2(time))
Processes all files whose DELETION-DATE lies within the specified time period (date1 <= DELETION-DATE <= date2). The upper and lower limits of the specified time period are defined more exactly by specifying a time.

DISKWR

Enables the user to select files for processing based on the time at which data consistency is required for them, as defined in the catalog entry.

= ANY
The time at which data consistency is required, as defined in the catalog, is not a selection criterion.

= IMMEDIATE
Processes all files for which data consistency is required immediately after a write operation is completed. Such files are not suitable for processing in a write cache.

= BY-CLOSE
Processes all files for which data consistency is not required until CLOSE processing. These files are suitable for processing in a write cache.

ENCRYPT

Enables the user to select files based on whether or with which encryption method they are encrypted.

= *ANY
Processes all files regardless of whether or with which encryption method they are encrypted.

= *NONE
Processes only those files which are not encrypted.

= *AES
Processes only those files which are encrypted with the AES encryption method.

= *DES
Processes only those files which are encrypted with the DES encryption method.

EXDATE

The user can select files to be processed on the basis of their expiration date. The expiration date of a file is defined in the catalog and specifies when the file may be updated again or deleted. If no expiration date is defined when creating the file, the expiration date is set to the creation date.
File generation groups and file generations are not taken into account.

The user may supplement date specifications by a time value; however, it should be noted that the time stamp for the expiration date is always set to 00:00:00 in the file catalog at present.
The rules for date and time specifications are described on "Format of date specifications". Ranges defined in intervals include both specified limits.

= ANY
The expiration date is not a selection criterion.

= NONE
Processes all files for which no expiration date has been entered in the catalog, i.e. files that have not yet been opened.

= date
Processes all files for which the specified expiration date is defined.

= (date[,])
Processes all files for which the expiration date is greater than or equal to the specified date.

= (,date)
Processes all files for which the expiration date is less than or equal to the specified date.

= (date1,date2)
Processes all files for which the expiration date lies within the specified period
(date1 <= expiration date <= date2).

= date(time[,])
Processes all files with the specified expiration date and with an expiration time that is greater than or equal to the specified time.
Note that the time of expiration (i.e. the time on the expiration date) is always entered as 00:00:00 hours in the catalog at present!

= date(time1,time2)
Processes all files with the specified expiration date and with a time of expiration that lies within the specified time interval.
Note that the time of expiration (i.e. the time on the expiration date) is always entered as 00:00:00 hours in the catalog at present!

= (date(time)[,])
Processes all files for which the expiration date and time is greater than or equal to the specified time.
Note that the time of expiration (i.e. the time on the expiration date) is always entered as 00:00:00 hours in the catalog at present!

= (,date(time))
Processes all files for which the expiration date and time is less than or equal to the specified time.
Note that the time of expiration (i.e. the time on the expiration date) is always entered as 00:00:00 hours in the catalog at present!

= (date1(time),date2(time))
Processes all files for which the expiration date lies within the specified period (date1 <= expiration date <= date2). The upper and lower limits of the specified period are defined more precisely by time values in both cases.

EXTENTS

Only for files on disks and on Net-Storage:
Allows the user to select files for processing on the basis of the specified number of extents. An extent is a contiguous area occupied by a file on a disk. The number of extents which make up a file is stored in the catalog.
A file on Net-Storage has precisely one extent.
File generation groups and file generations are not taken into account.

The possible values for “nmbr” are: 0 <= nmbr <= 65535. Range specifications include both upper and lower limits.

= ANY
The number of extents is not a selection criterion.

= nmbr
Only the files with exactly the specified number of extents are processed.

= (nmbr [,])
Only the files with at least the specified number of extents (number of extents >= nmbr) are processed.

= (,nmbr)
Only the files that have at most the specified number of extents (number of extents <= nmbr) are processed.

= (nmbr1, nmbr2)
Only the files that have at least as many extents as “nmbr1” and at most as many extents as “nmbr2” (i.e. nmbr1 <= number of extents <= nmbr2) are processed.

FCBTYPE

Allows the user to select files for processing on the basis of the access method with which they were created. The access method is entered into the file catalog when the file is created. It corresponds to the specification for FCBTYPE in the FILE macro.
File generation groups and file generations are not taken into account.

= ANY
The access method is not a selection criterion.

= NONE
Processes only those files for which no access method has been entered in the catalog, i.e. files which have not yet been opened.

= ISAM
Processes only those files which were created with the ISAM access method.

= BTAM
Processes files for that were created with the BTAM access method (BTAM files). BTAM files are tape files, and can therefore only be exported (see the action operand CATALOG).

= SAM
Processes files that were created with the SAM access method (SAM files).

= PAM
Processes files that were created with the UPAM access method (PAM files).

= (list-of-fcbtype)
More than one access method may be specified in a list. All files that were created with one of the specified access methods will be processed.

FILTYPE

The user can select the files to be processed according to the file type.

= *ANY
The file type is not a selection criterion.

= *BS2000
BS2000 files are processed.

= *NODE
Files are processed which are created as node files.

FSIZE

Only for disk files on disk and on Net-Storage:
Allows the user to select files for processing on the basis of the number of free PAM pages. The free PAM pages of a file indicate the amount of reserved but unused storage space.File generation groups and file generations are not taken into account.

“number” must be: 0 <= number <= 2147483647; if ranges are specified, the limit values are included in the range.

= ANY
The size of the free (= reserved but unused) storage space is not a selection criterion.

= SIZE
Only the files for which none of the reserved pages are used (i.e. for which no PAM page has been written) are processed.

= nmbr
Processes files with exactly the specified number of reserved but unused PAM pages.

= (nmbr[,])
Processes files with at least the specified number of reserved but unused PAM pages (free PAM pages >= nmbr).

= (,nmbr)
Processes files with no more than the specified number of reserved but unused PAM pages (free PAM pages <= nmbr).

= (nmbr1,nmbr2)
Processes files for which the number of free pages lies within the specified range (nmbr1 <= free PAM pages <= nmbr2). 

GROUPAR

Selects and processes files on the basis of the access rights that are defined for members of the file owner's user group in BASIC-ACL entries.

= ANY
The BASIC-ACL entries for members of the file owner's user group are not a selection criterion.

= NO-ACCESS
Processes all files that cannot be accessed by the user group of the owner.

= access-list
Only processes files for which at least one of the access rights specified in the list has been entered for the file owner's user group in the BASIC-ACL entry.

The access list has the following format:

• • • Long format:

      ([READ=YES / READ=NO][,WRITE=YES / WRITE=NO][,EXEC=YES / EXEC=NO])

    • Short format:

      ([R=Y / R=N][,W=Y / W=N][,X=Y / X=N])

The parentheses constitute part of the operand value and must be specified.

The individual elements of the access list mean the following:

READ=YES or R=Y	Processes all files to which the user group of the owner has read access.
READ=NO or R=N	Processes all files to which the user group of the owner does not have read access.
WRITE=YES or W=Y	Processes all files to which the user group of the owner has write access.
WRITE=NO or W=N	Processes all files to which the user group of the owner does not have write access.
EXEC=YES or X=Y	Processes all files which the user group of the owner may execute.
EXEC=NO or X=N	Processes all files which the user group of the owner may not execute.

GUARDS

The user can select files to be processed on the basis of the access protection defined by GUARDS (see the “SECOS” [8] manual).

= *ANY
The access protection defined by GUARDS is not a selection criterion.

= *NONE
Processes all files which have no access protection defined by GUARDS.

= *YES
Processes all files which have access protection defined by GUARDS. 

= (READ=...,WRITE=...,EXEC=...)
The type of access protection provided by GUARDS that is to be used as a selection criterion can be defined by the user in a list. For each access mode (read, write, and execute), the defined protection can be specified precisely. If no entry is made for an access mode, the protection defined for that access mode has no effect on the selection.

For each access mode, one of the following values may be specified: 

*ANY	The defined GUARDS protection is not a selection criterion.
*NONE	No guard has been defined for the specified access mode, i.e. the corresponding access is denied.
fname	All conditions for granting access in the specified access mode are defined in the guard fname.

IGNORE

The user can define whether defined protection against write access or a defined retention period is to be ignored.
The IGNORE operand replaces the call to the CATAL macro which would be otherwise required to reset the protection attributes for the files to be processed before calling the ERASE macro.

= ANY
If no operand is specified here, all specified protection attributes are taken into account for ERASE processing.

= ACCESS
Enables files which are protected against write access by the owner to be selected for deletion with ERASE. Existing write protection is ignored. This specification is ignored if there is a TSOS restriction for a file under a foreign user ID.

= EXDATE
Allows files for which a retention period exists (expiration date > current date) to be erased. Existing retention periods are ignored.

= RDPASS
For system administration only:
Allows files which are protected by a read password to be erased during ERASE processing. Existing access protection by a read password is ignored.

= WRPASS
For system administration only:
Allows files which are protected by a write password to be erased during ERASE processing. Existing access protection by a write password is ignored.

= EXPASS
For system administration only:
Allows files which are protected by an execute password to be erased during ERASE processing. Existing access protection by an execute password is ignored.

= (list-of-ignore)
The operand values ACCESS and IGNORE can be specified in a list, i.e. both protection attributes are ignored. 

IOPERF

Processes all files based on the performance attribute that is defined for them in the catalog (see the IOPERF operand in the CATAL macro).

= ANY
The performance attribute is not a selection criterion.

= STD
Processes all files for which the performance attribute was defined as STD.

= HIGH
Processes all files for which the performance attribute was defined as HIGH (high performance priority).

= VERY-HIGH
Processes all files for which the performance attribute was defined as VERY-HIGH (highest performance priority).

= (list-of-ioperf)
Up to three performance attributes may be specified in a list. All files that have one of these specified attributes will be shown.

IOUSAGE

The user can select the files to be processed, depending on the type of I/O operations to which the performance attribute applies (see the IOUSAGE operand in the CATAL macro).

= ANY
The performance attribute is not a selection criterion.

= RDWRT
Processes all files for which the performance attribute applies to read and write operations.

= WRITE
Processes all files for which the performance attribute applies to write operations only.

= READ
Processes all files for which the performance attribute applies to read operations only.

= (list-of-iousage)
More than one type of I/O operation may be specified in a list. All files for which the performance attribute applies to at least one of the specified I/O operations will be shown.

LADATE

Processes all files with the corresponding date of last access. File generation groups and file generations are not taken into account.

The user can supplement date specifications by specifying time values. The rules for date and time specifications are described on "Format of date specifications".
Ranges specified in intervals include both upper and lower limits.

= ANY
The last access date is not a selection criterion.

= NONE
Processes all files for which no last access date has been entered in the catalog, i.e. files that have not yet been opened.

= date
Selects files which were last accessed on the specified date.

= (date[,])
Processes all files that were last accessed on or after the specified date
(last access date >= date).

= (,date)
Selects all files that were accessed on or before the specified date
(last access date <= date).

= (date1,date2)
Processes all files that were last accessed during the specified period
(date1 <= last access date <= date2).

= date(time[,])
Processes all files that were last accessed on the specified date on or after the specified time.

= date(time1,time2)
Selects all files that were last accessed on the specified date and within the specified period.

= (date(time)[,])
Selects all files that were last accessed on or after the specified date and time.

= (,date(time))
Selects all files that were last accessed before the specified date and time.

= (date1(time),date2(time))
Selects all files that were last accessed within the specified period. The upper and lower limits of the specified period are defined more accurately by means of a time specification.

LASTPAG

Selects and processes files based on the amount of storage space used (i.e. the number of PAM pages written). The last-page pointer is set to the highest used PAM page.

= ANY
The storage space used is not a selection criterion.

= nmbr
Processes all files for which exactly the specified number of PAM pages have been written.

= (nmbr[,])
Processes all files for which the number of used PAM pages is greater than or equal to the specified value.

= (,nmbr)
Processes all files for which the number of used PAM pages is less than or equal to the specified value. 

= (nmbr1,nmbr2)
Processes all files for which the number of written PAM pages lies in the interval defined by nmbr1 and nmbr2 (nmbr1 <= used PAM pages <= nmbr2).

Any integers from the range 0 <= nmbr <= 2147483647 may be specified. 

LCDATE

Selects and processes files based on the date on which they were last accessed for writing (last change date). File generation groups and file generations are not taken into account.

The user can supplement date specifications by means of time values. The rules for date and time specifications are described on "Format of date specifications". Ranges defined by intervals include both the specified limits.

= ANY
The date of last write access is not a selection criterion.

= NONE
Processes all files for which no date of last write access is entered in the catalog, i.e. files that have not yet been opened.

= date
Processes all files that were last written to (i.e. changed) on specified date.

= (date[,])
Processes all files that were last changed on or after the specified date
(last change date >= date).

= (,date)
Processes all files that were last changed on or before the specified date
(last change date <= date).

= (date1,date2)
Processes all files that were last changed during the specified period
(date1 <= last change date <= date2).

= date(time[,])
Processes all files that were last changed on the specified date on or after the specified time.

= date(time1,time2)
Processes all files that were last changed on the specified date and within the specified period.

= (date(time)[,])
Processes all files that were last changed on or after the specified date and time.

= (,date(time))
Processes all files that were last changed before the specified date and time.

= (date1(time),date2(time))
Processes all files that were last changed within the specified period. The upper and lower limits of the specified period are defined more precisely by time values. 

LIST

The user can specify whether successful execution of ERASE processing is to be logged and whether errors which occur during processing are to be reported on SYSOUT. Otherwise, errors are reported only via the return code field.

Default value:

no additional log is created.

= ERRORS-TO-SYSOUT
Errors (with the exception of errors ignored via NOSTEP) are logged on SYSOUT.

= (area,len)
The names of all files affected by ERASE are written into a user output area.

(area,len) means: (adr / (r1),length / equ / (r2))

addr	Symbolic address of the output area.
r1	Register r1 contains the address of the output area.
length	Length of the output area, specified as a constant.
equ	Length of the output area, specified as an equate.
r2	Register r2 contains the length of the output area.

The entries are written sequentially into the output area. Each entry has the following format:

RL D RC pathname EC

RL	Record length (field length: 2 bytes); shows the length of an information unit.
D	2 bytes, reserved.
RC	Return code (field length: 4 bytes); this contains the DMS error code, which can be evaluated with the aid of the IDEMS macro.
pathname	Path name of the file (field length: variable).
EC	End criterion (field length: 2 bytes)

The end of the output in the output area is indicated with X'00' in EC field. In the event of an output area overflow, subcode 2 in the error code is set to '1' and processing continues without further logging.

Since the internal buffer areas are limited, an overflow may be indicated during RFA access, even though the user has provided a sufficiently large output area. In this case, output has been terminated prematurely.

MANCLAS

The user can select the files to be processed according to the HSMS management class for data backup to SM pubsets.

= *ANY
The HSMS management class is not a selection criterion.

= *NONE
Only files for which no HSMS management class is defined are selected.

= <c-string 1..8>
Only files with the specified HSMS management class are selected.

MF

The forms of the MF operand are described in detail in the appendix ("Macro types"). In all macros differentiated by the MF operand (MF=L/E/D), the version operand must contain the same value.
This description covers all operands supported in BS2000/OSD-BC >= V3.0.
VERSION=3 must be specified for generating this format.

MIGRATE

The user can use the migration attribute defined in the catalog entry (see the MIGRATE operand of the CATAL macro, "CATAL - Process catalog entry") to select files for processing with ERASE.

= ANY
The specified files are processed, regardless of what value is defined for MIGRATE in the catalog entry.

= ALLOWED
Only those files are processed for which the corresponding operand value has been specified in the catalog entry, i.e. files which may be migrated to storage levels S1 and S2.

= INHIBIT
Only those files are processed for which MIGRATE=INHIBIT has been specified in the catalog entry, i.e. files which may be briefly migrated (e.g. for reorganization purposes).

= FORBIDDEN
Only those files are processed for which the corresponding operand value has been specified in the catalog entry, i.e. files which must not be migrated.

= (list-of-migrate)
The ALLOWED and INHIBIT values may be specified by the user in a list. All files for which one of the specified values was defined in the catalog will be processed.

MOUNT

Only for files on private disks:
The user can specify if when erasing a file on private disk, only the first or all private disks involved are to be available online.
The MOUNT operand should be specified together with SPACE-CATALOG or DESTROY; it must be specified if DATA is specified.

Any MOUNT operand specified for tape files or files on public volumes is ignored.

Default value:

MOUNT = FIRST-DISK

= FIRST-DISK 

Only the private disk containing the beginning of the file and the catalog entry must be online.

= ALL-DISK
All private disks on which sections of the file are stored must be online. If any disk is missing, the file is not erased.

NOSTEP

The user can specify which errors are not to be reported via a return code in register 15.

= NONE
All errors are to be reported via return code.

= errcode
The user can specify the DMS error codes of the errors which are to be ignored, i.e. not reported via the return code field in the standard header.

"error code" means: const / equ

const equ

The error code is specified as a decimal or hexadecimal constant. The error code is specified as an equate.

It is advisable to use the equates generated by the IDEMS macro.

The list (errcode,...) may contain up to three elements.

OTHERAR

Selects and processes files based on the access rights that are defined via BASIC-ACL entries for all users other than the file owners's user group.

= ANY
BASIC-ACL entries for all users other than the file owner's user group are not a selection criterion.

= NO-ACCESS
Processes all files that may be accessed by users not belonging to the file owner's user group.

= access-list
Only processes files for which at least one of the listed access rights has been entered for users not in the file owner's user group in the BASIC-ACL entry.

“access list” has the following format:

• • • Long format:

      ([READ=YES / READ=NO][,WRITE=YES / WRITE=NO][,EXEC=YES / EXEC=NO])

    • Short format:

      ([R=Y / R=N][,W=Y / W=N][,X=Y / X=N])

The parentheses form part of the operand values and are mandatory. The individual elements of the access list mean the following:

READ=YES or R=Y	Processes all files to which users not in the owner's user group have read access.
READ=NO or R=N	Processes all files to which users not in the owner's user group do not have read access.
WRITE=YES or W=Y	Processes all files to which users not in the owner's user group have write access.
WRITE=NO or W=N	Processes all files to which users not in the owner's user group do not have write access.
EXEC=YES or X=Y	Processes all files which users not in the owner's user group may execute.
EXEC=NO or X=N	Processes all files which users not in the owner's user group may not execute.

OWNERAR

Processes files selected on the basis of the access rights that are defined for the file owner in the BASIC-ACL entries.

= ANY
BASIC-ACL entries for file owners are not a selection criterion.

= NO-ACCESS
Processes all files that the owner is not allowed to access.

= access-list
Only processes files for which at least one of the listed access rights has been entered for the file owner in the BASIC-ACL entry.

“access list” has the following format:

• • • Long format:

      ([READ=YES / READ=NO][,WRITE=YES / WRITE=NO][,EXEC=YES / EXEC=NO])

    • Short format:

      ([R=Y / R=N][,W=Y / W=N][,X=Y / X=N])

The parentheses form part of the operand value and must be specified. The individual elements of the access list mean the following:

READ=YES or R=Y	Selects all files that may be accessed by the owner for reading.
READ=NO or R=N	Selects all files that cannot be accessed by the owner for reading.
WRITE=YES or W=Y	Selects all files that can be accessed by the owner for writing.
WRITE=NO or W=N	Selects all files that cannot be accessed by the owner for writing.
EXEC=YES or X=Y	Selects all files that may be executed by the owner.
EXEC=NO or X=N	Selects all files that the owner is not allowed to execute.

PASS

The user can use the password type to select the files to be processed by ERASE.

= ANY
Password protection is not a selection criterion.

= NONE
Only files for which no passwords are defined are processed.

= EXPASS
Only files protected by an execute password are processed.

= RDPASS
Only files protected by a read password are processed.

= WRPASS
Only files protected by a write password are processed.

= (list-of-pass)
The user may specify more than one type of password in the form of a list. All files protected by one of the specified password types will be processed.

PASSWD

The user can specify one or more passwords to permit files protected by these passwords to be erased. The specified password must not be entered in the password table of the job. Note that the passwords entered here are valid only for the current ERASE macro.

The passwords must comply with the rules for password definition. The passwords are not reproduced in plaintext in any logs created by ERASE.

If no specification is entered, none of the files protected by a password will be processed by ERASE.

= ANY
No password is passed to ERASE.

= password
Protection by this password is to be cancelled.

= (list-of-passwd)
Up to three passwords may be specified in the form of a list.

POS

Only for file generations:
Wildcards may be used in “pathname” everywhere except in the generation number, which must be entered as an absolute or relative generation number. The generation identified by “pathname” must exist and is not erased.

Depending on the operand value AFTER/BEFORE, all younger or all older file generations are erased, and the catalog entry is updated as follows:

• If the oldest generation is erased, the generation specified in “pathname” becomes the oldest generation.

• If the youngest generation is erased, the generation specified in “pathname” becomes the youngest generation.

• If the generation with relative generation number 0 is erased, the generation specified in “pathname” becomes the base generation.

= AFTER
All generations selected by “pathname” and with a generation number greater than that specified in “pathname” are erased.  
= BEFORE
All generations selected by “pathname” and with a generation number less than that specified in “pathname” are erased.

PREFIX = pre

Only in conjunction with MF=D:
“pre” is a 1-3 character string which replaces the corresponding string at the beginning of the generated names and thus creates macro-specific names. The first character of “pre” must be a letter.

PREFORM

Erases files depending on their (intended) file format on SM pubsets.

= *ANY
The file format is not a selection criterion.

= *NONE
Erases all files for which no PREFORM value was defined.

= *K
Erases all files with the intended file format *K.

= *NK2
Erases all files with the intended file format *NK2.

= *NK4
Erases all files with the intended file format *NK4.

= (list-of-preform)
Erases all files which have one of the specified file formats. The list may contain any values except for ANY.

PROTACT

The user can select files to be erased on the basis of the protection level provided by the highest activated access control.

When the file is accessed, the highest activated protection level applies. The following table shows the method used for access control, the protection attribute to be specified in the CATAL macro and the file protection hierarchy (protection levels):

Access control method	Protection attribute	Protection level
Standard access control	ACCESS and SHARE	0
Basic access control list	BASACL, OWNERAR, GROUPAR, OTHERAR	1
Access control using GUARDS	GUARDS	2

All other protection attributes of the file (e.g. passwords) are evaluated independently, without regard to the implemented protection level.

= ANY
The files to be processed are selected without regard to the protection level of the highest activated access control.

= LEVEL-0
Processes files for which access is controlled via standard access control.

= LEVEL-1
Processes files for which access is controlled via a basic access control list (BASIC-ACL protection).

= LEVEL-2
Processes files for which access is controlled by GUARDS.

= (list-of-protact)
The user may specify up to a maximum of three protection levels in a list. All files for which the protection level of the access control method matches one of those specified are selected.

RELSPAC

Selects files for processing on the basis of the lock to prevent the release of unused memory space (defined in the FILE macro or the MODIFY-FILE-ATTRIBUTES command). The lock can be defined in the catalog by using the CATAL macro.

= ANY
The lock preventing release of unused memory space is not a selection criterion.

= ALLOWED
Selects all files for which unused memory space may be released.

= IGNORED
Selects all files for which the release of unused memory space is not permitted.

SHARE

Selects files to be erased on the basis of whether or not they are shareable (see the SHARE operand in the CATAL macro).

= ANY
Shareability is not a selection criterion.

= YES
Processes all files that are shareable, i.e. which are also accessible to other user IDs under active standard access control.

= NO
Processes all files that are not shareable, i.e. only accessible to the owner under active standard access control.

= SPECIAL
Processes all shareable files (see YES) that can also be accessed by user IDs with hardware maintenance privileges.

= (list-of-share)
One or more operand values may be specified in a list.

SIZE

Only for disk files:
The user can use the file size or the size of the reserved space (= number of PAM pages) to select the files to be processed by ERASE. File generation groups and file generations are not included.

“number” specifies a number of PAM pages, where 0 <= number <= 2147483647.
Range specifications are inclusive of the limit values.

= ANY
The size of the reserved storage space is not a selection criterion.

= FSIZE
Only files for which space has been reserved but not actually used (LASTPG = 0) are processed, i.e. files which have not yet been opened.

= nmbr
Only files for which precisely the specified number of PAM pages have been reserved are processed.

= (nmbr[,])
Only file for which at least the specified number of PAM pages have been reserved are processed (SIZE >= nmbr).

= (,nmbr)
Only files for which not more than the specified number of PAM pages have been reserved are processed (SIZE <= nmbr).

= (nmbr1,nmbr2)
Only files for which a number of PAM pages in the range “nmbr1” to “nmbr2” have been reserved are processed.

SLEVEL

The user can use the storage level to select the files which are to be processed by ERASE. HSMS supports the following storage levels:

S0:	implemented via disk storage devices with fast access (online processing).
S1:	implemented via high capacity disk storage devices (online background level).
S2:	implemented via magnetic tape or magnetic tape cartridge archives (offline background level).

= ANY
The specified files are processed regardless of the storage level on which they are stored.

= S0
Only those files stored on level S0 are processed.

= S1
Only those files stored on level S1 are processed.

= S2
Only those files stored on level S2 are processed.

= (list-of-slevel)
The user may specify up to 3 storage levels in the form of a list. Only the files on one of the specified storage levels will be processed.

STATE

The user can select files to be processed on the basis of their current processing state.

= ANY
The storage level is not a selection criterion.

= NOCLOS
Processes all files which have been opened for writing and are not closed. Such files include:

• • • normally open files (OPEN mode OUTIN, INOUT, OUTPUT)

    • files not closed in a previous session

    • files not closed in the current session because of job abortion.

= CLOSED
Processes all files that have already been closed, i.e. files not selected by NOCLOS.

= CACHED
Processes the files which are currently cached.

= NOT-CACHED
Processes all files which are not being currently processed in a cache.

= CACHE-NOT-SAVED
Processes all files for which it was not possible to save all data from the cache to a disk during closing.

= REPAIR-NEEDED
Processes all files which were not closed in an earlier session and which have not yet been verified (see VERIFY macro).

= DEFECT-REPORTED
Processes all files which may contain defective disk blocks.

= NO-OPEN-ALLOWED
Processes all files which cannot be opened due to data inconsistency.

= OPEN-ALLOWED
Processes all files that can be opened.

= (list-of-state)
A list of values may be specified (with a maximum of 4 file states). All files which are in one of the specified states are processed.

STOCLAS

The user can select the files to be processed according to the storage class for file storage on SM pubsets.

= *ANY
The storage class is not a selection criterion.

= *NONE
Selects all files for which no storage class is defined.

= <c-string 1..8>
Selects all files with the specified storage class.

STOTYPE

The user can select the files to be processed according to the storage type.

= *ANY
The storage type is not a selection criterion.

= *PUBSPACE
Only files on public volumes are selected.

= *NETSTOR
Only files on Net-Storage volumes are selected. 

SUPPORT

The user can select the files to be processed by ERASE on the basis of the volume type. File generation groups and file generations are not included.

= ANY
Volume type is not a selection criterion.

= PUBLIC
Only files on public disks and on Net-Storage are processed.

= PRDISC
Only files on private disks are processed.

= TAPE
Only files on tapes or tape cartridges are processed.

= (list-of-support)
A list of values may be specified (with up to 3 volume types). All files which are stored on one of the specified volume types will be processed.

S0MIGR

Files are processed dependent on whether reallocation (migration) to the S0 level is allowed.

= *ANY
The migration allowance is not a selection criterion.

= *ALLOWED
All files for which migration within the S0 level is allowed are processed.

= *FORBIDDEN
All files for which migration within the S0 level is not allowed are processed.

= (list-of-s0migr)
The user can specify the desired values in a list. All files for which one of the specified values is defined in the catalog are processed.

TIMBASE

Defines whether the absolute date definitions are in UTC or local time. This affects the CRDATE, DELDATE, EXDATE, LADATE and LCDATE operands. Relative dates are always based on local time.

= *UTC
Absolute dates are specified in UTC time.

= *LTI
Absolute dates are specified in local time. 

TYPE

Processes files selected on the basis of their file type. The TYPE operand also determines which selection criteria are evaluated for ERASE processing. File generation groups and file generations are not taken into account by any of the selection parameters.

= ANY
ERASE processes “normal” files, file generation groups and file generations. However, FGGs and file generations are ignored by some of the selection operands in order to avoid the creation of gaps in the sequence of generations.

= FILE
File generation groups and file generations are not processed by ERASE; all other selection operands are evaluated.

= FGG
Processes file generation groups and file generations only. The only sensible selection operands for TYPE=FGG are those which refer to attributes that are identical for all generations of an FGG (ACCESS, BACKUP, CCS, DELDATE, EXDATE, MANCLAS, MIGRATE, PASS, RELSPAC, SHARE, SUPPORT=PRDISC and WORKFIL).

File generation groups or file generations are not selected if:

• • • the selection operand VOLUME is not specified together with CATALOG or does not designate a private disk,

    • a selection operand that is not the same for all generations/FGGs is specified.

= PLAM
Processes PLAM libraries. This is a subset of the files which are selected by the TYPE=FILE specification.

= (list-of-type)
A maximum of three file types can be specified by the user in the form of a list. Only the files which match one of the specified file types are selected.

USRINFO

The user can select files/file generations for processing dependent on the user-specific metainformation.

= *ANY
The user-specific metainformation is not a selection criterion.

= *NONE
All files possessing no user-specific metainformation are processed.

= <c-string 1..8>
All files with the specified user-specific metainformation are processed. 

VERSION

Specifies which version of the parameter list is to be generated.

= 0
Default value: generates the parameter list format that was supported prior to BS2000 V9.5A.
This format will, however, only support parameters which were known at that time. For example, the path name can only be specified without wildcards, and only VOLUME and POS are permitted as selection parameters. The supported operands and operand values can be found in section "Variations in versions - VERSION=0/1/2".

= 1
Generates the parameter list format that was supported in BS2000 V9.5 and V10.0. This format will support only parameters which were known at the time. The supported operands and operand values can be found in section "Variations in versions - VERSION=0/1/2".

= 2
Generates the parameter list format for versions as of BS2000/OSD V1.0.

= 3
Generates the parameter list format for versions as of BS2000/OSD V3.0.

Note

If existing software which manipulates the generated parameter list is to be recompiled or reassembled, the old format must be requested. Otherwise, source compatibility is ensured.

VOLSET

The user can select the files to be processed via the volume set on which they reside.

= *ANY
The volume set is not a selection criterion.

= <c-string 1..4>
All files on the specified volume set are selected.

VOLUME

The user can select files to be processed on the basis of the VSN (volume serial number) of the disks on which they are stored.

= *ANY
All files are processed regardless of the VSNs of their volumes.

= vsn
Processes all files that occupy storage space on the specified volume. If any of the action operands SPACE, SPACE-CATALOG, DATA and DESTROY is specified at the same time, no file generations and file generation groups are selected. If the action operand CATALOG is specified with the VSN, no file generations on tape are selected. 

WORKFIL

The user can select the files on SM pubsets to be processed dependent on whether they can be deleted by the system administrator (work files).

= *ANY
Whether or not the files are work files is not a selection criterion.

= *NO
All files that are not work files are processed.

= *YES
All work files are processed.

Programming notes

1. The error code is now only stored in the standard header of the parameter list and no longer in register 15 as was the case up to VERSION=2.

2. Error code 06D6 – “filename” was partially qualified and the system could not erase all matching files.

3. Error code 05DF – *SYSOUT not permitted in interactive mode.

4. In specific error cases (parameter range not accessible or not set up), program termination with STXIT connection is initiated.

Return codes

Standard header: ccbbaaaa

The following code relating to execution of the ERASE macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):

X'cc'	X'bb'	X'aaaa'	Meaning
	X'00'	X'0000'	No error
	X'40'	X'0501'	Requested catalog not available
	X'82'	X'0502'	Requested catalog in the rest state
	X'40'	X'0503'	Incorrect information in the MRSCAT
	X'82'	X'0504'	Error in catalog management system
	X'40'	X'0505'	Computer communication error (MRS)
	X'80'	X'0506'	Operation canceled because of master change
	X'40'	X'0510'	Error while calling an internal function
	X'40'	X'0512'	Requested catalog unknown
	X'40'	X'051A'	File already exists
	X'40'	X'051B'	User ID not known in specified pubset
	X'40'	X'051C'	No access right to specified pubset
	X'40'	X'051D'	LOGON password different on specified pubset
	X'20'	X'0530'	Error in storage space request
	X'20'	X'0531'	Unexpected catalog access error
	X'82'	X'0532'	File in use, therefore locked
	X'40'	X'0533'	File not found
	X'82'	X'0534'	Private volume cannot be allocated
	X'40'	X'0535'	No access right to the file catalog entry
	X'20'	X'053B'	System error during file access
	X'40'	X'053D'	Catalog or F1 label block is destroyed
	X'82'	X'053F'	File reserved by another task
	X'20'	X'054F'	Unexpected error during access to JOIN file
	X'40'	X'055C'	Catalog entry on private disk not found
	X'01'	X'0571'	System file declared as *DUMMY
	X'40'	X'0572'	System file not assigned to a DMS file
	X'40'	X'0574'	DMS error during deletion of a system file
	X'82'	X'0575'	System command active for this system file
	X'01'	X'0576'	Contradictory operand combination or reserved fields of the parameter area used
	X'20'	X'0577'	Internal error during access to job environment
	X'20'	X'0578'	Internal error during checking of access rights
	X'40'	X'057C'	HSMS has rejected recall
	X'40'	X'057D'	HSMS file displaced. Cannot be retrieved without delay.
	X'40'	X'057E'	HSMS not available
	X'82'	X'0594'	Not enough virtual memory available. This return code can also occur in particular in conjunction with a selection specification (wildcard) if too many files are selected
	X'01'	X'0599'	Operand is not supported in the RFA-BS version
	X'01'	X'05AB'	Address of output area incorrect or not specified
	X'01'	X'05AC'	Incorrect second operand
	X'40'	X'05B3'	Only the system administrator is allowed to specify a foreign user ID
	X'40'	X'05BF'	File protected with password
	X'82'	X'05C3'	File generation to be erased is locked
	X'01'	X'05C5'	SPACE specification for files on private disks is not allowed
	X'40'	X'05C6'	Release data does not permit deletion of file
	X'20'	X'05C7'	Internal error in DMS
	X'01'	X'05C9'	Only files on private volumes can be exported
	X'82'	X'05D0'	File in use, therefore locked
	X'01'	X'05DE'	File name not found or not allowed
	X'01'	X'05EE'	File name too long
X'02'	X'00'	X'05F7'	File generation does not exist but group entry will be changed
	X'01'	X'05FA'	Access to remote imported pubset not possible
	X'40'	X'05FC'	Specified user ID not in home pubset
	X'40'	X'0609'	Action for system file not permitted
	X'40'	X'0640'	Access to Net-Storage is rejected by the ONETSTOR subsystem because of communication problems with the net client
	X'40'	X'0643'	Net client reports access error
	X'40'	X'0644'	Net client reports internal error
	X'40'	X'0645'	File does not exist on Net-Storage
	X'40'	X'0649'	Net server reports POSIX ACL error
	X'40'	X'064A'	Net client reports that access to files on the Net-Storage volume is forbidden
	X'40'	X'064B'	Access to node files from the net client not supported
	X'40'	X'064C'	Directory of the specified user ID does not exist on the net server
	X'40'	X'0666'	File is write-protected by GUARDS
	X'20'	X'069D'	Incorrectly structured catalog entry
X'01'	X'00'	X'06B4'	No generation to be erased exists before or after the specified generation
	X'01'	X'06C7'	Invalid generation number specified
	X'40'	X'06CC'	Only with selection specification (wildcard): no file matches the selection specification
	X'01'	X'06D4'	Invalid generation specification
	X'40'	X'06D5'	File protected
X'02'	X'00'	X'06D6'	Error during deletion of some files
	X'01'	X'06F5'	No authorization for use of specified operands (TPR or TSOS required)
	X'01'	X'06F9'	Either the file name or the volume must specified
	X'01'	X'06FD'	Parameter area invalid or not accessible
	X'40'	X'06FF'	BCAM connection aborted
	X'01'	X'FFFF'	Wrong function number in parameter area header
	X'03'	X'FFFF'	Wrong version number in parameter area header