VTOC-UPDATE

#### Search Results

Search

# VTOC-UPDATE

File | 7
Op-Sys | z/OS, z/VSE, BS2000 Note Support for z/VSE is deprecated. Support for BS2000 is also deprecated, except in conjunction with the ESM adapter. Features that are z/VSE and BS2000 specific will be removed from future releases.
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

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
--- | --- | --- | --- | ---
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

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

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

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

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

Possible functions are:

Function | Explanation
--- | ---
`PURGE` | Delete dataset or file regardless of expiration date.
`RELEASE` | In z/OS, release unused space. In BS2000, 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

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

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

Field Name | Type/Length | Operating System
--- | --- | ---
`PASSWORD` | (A8) | BS2000

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

### On this page

- Common Fields for all Operating Systems
- Additional Field Supported for z/OS, z/VSE
- Additional Fields Supported for z/OS
- Additional Fields Supported for BS2000
- Relevant Error Codes
- Field Descriptions