VTOC-UPDATE

File 7
Op-Sys z/OS, z/VSE, BS2000/OSD
Statement PROCESS
Task Perform VTOC updates, for example, rename, scratch, purge datasets.

Common Fields for all Operating Systems

Dictionary Field Name F/L Mu DE Remarks
ERROR-CODE N3      
ERROR-TEXT A58      
NODE N5   D  
NODE-NAME A16   D  
SYSTEM-MESSAGE-CODE A10      
DSNAME A54   D Required.
NEWNAME A54   D Relevant for FUNCTION=RENAME.
FUNCTION A8   D Required for z/OS, z/VSE.

Additional Field Supported for z/OS, z/VSE

Dictionary Field Name F/L Mu DE Remarks
VOLSER A6   D Required.

Additional Fields Supported for z/OS

Dictionary Field Name F/L Mu DE Remarks
LEAVE N5   D Relevant for FUNCTION=RELEASE..
CATALOG-UPDATE A3   D Relevant for FUNCTION=RENAME or SCRATCH.
WAIT A3   D Relevant for VOLSER=MIGRAT.

Additional Fields Supported for BS2000/OSD

Dictionary Field Name F/L Mu DE Remarks
SYSTEM-CODE B2      
ERASE-OPTION A7   D  
ERASE-RANGE A1   D  
PASSWORD A8   D  

Relevant Error Codes

Code Text z/OS z/VSE BS2000/OSD
530 Access denied by Security Facility.     X
535 File has invalid format. X    
539 DFHSMREQ failed with RC=... X    
556 File is in use.     X
565 Syntax error in dataset name.     X
571 DSNAME missing. X X  
572 NEWNAME missing.   X X
573 SCRATCH invalid.   X  
574 RENAME invalid.   X  
600 Unknown function. X X X
659 Dataset is already cataloged.     X
701 DSNAME missing.     X
722 Requested dataset not found.     X
733 User ID does not exist.     X
750 Invalid operand within operand list.     X
798 Task was not started under TSOS.     X
799 Entire System Server internal error.     X
851 File not on volume. X X  
852 No password supplied / VSAM data space. X    
853 Retention cycle unexpired / NEWNAME exists. X X X
856 Error xx while processing VTOC.   X  
856 Error assigning a logical unit.   X  
857 VTOC is in use.   X  

Field Descriptions

Field Name Type/Length Operating System
CATALOG-UPDATE (A3) z/OS

Update catalog after a file is scratched or renamed. Possible options:

Option Explanation
NO  Catalog is not updated.
YES  Catalog is updated.
Field Name Type/Length Operating System
DSNAME (A54) z/OS, z/VSE, BS2000/OSD

Fully qualified dataset name. In BS2000/OSD, fully qualified file name.

Field Name Type/Length Operating System
ERASE-OPTION (A7) BS2000/OSD

Possible options:

Option Explanation
CATALOG  Erase only catalog entry (only for tape files and private disks. Default for tape files).
DATA  Erase only data: keep allocated space and catalog entry (not valid for tape files).
DESTROY  Overwrite with x'00' (not valid for tape files).
SPACE  Same as DATA, but release allocated space (not valid for tape files and private disks).
Field Name Type/Length Operating System
ERASE-RANGE (A1) BS2000/OSD

Range of generation files to be deleted. Possible options:

Option Explanation
A  All files after the generation number in DSNAME.
B  All files before the generation number in DSNAME.
Field Name Type/Length Operating System
FUNCTION (A8) z/OS, z/VSE, BS2000/OSD

Possible functions are:

Function Explanation
PURGE  Delete dataset or file regardless of expiration date.
RELEASE  In z/OS, release unused space.

In BS2000/OSD, this function can be performed by FUNCTION=COMPRESS in the view FILE-MAINTENANCE.

This function is not supported in z/VSE.
RENAME  Rename dataset or file.
SCRATCH  Delete dataset or file.

In z/VSE, SCRATCH is equivalent to PURGE.

Field Name Type/Length Operating System
LEAVE (N5) z/OS

Number of free tracks after the unused tracks are freed with FUNCTION=RELEASE.

Field Name Type/Length Operating System
NEWNAME (N54) z/OS, z/VSE, BS2000/OSD

Relevant when FUNCTION=RENAME. New name to be assigned to the dataset or file.

In BS2000/OSD, must be supplied without CAT-ID / User ID.

Field Name Type/Length Operating System
PASSWORD (A8) BS2000/OSD

Password for write access to file to be renamed or deleted.

Field Name Type/Length Operating System
VOLSER (A6) z/OS, z/VSE

Volume serial number.

Field Name Type/Length Operating System
WAIT (A3) z/OS

Relevant when VOLSER=MIGRAT. Possible values are:

Value Explanation
YES  Wait for the dataset to be recalled from a migration volume before deleting it.
NO  Delete the migrated dataset without recalling (default).