FILE-ALLOCATE

#### Search Results

Search

# FILE-ALLOCATE

File | 9
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 | Enables the allocation of files from a Natural session.

## 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.
`VOLSER` | A6 |  | D | Required in z/VSE . `VOLSER` or `UNIT` is required in z/OS.
`DSORG` | A4 |  | D |
`UNIT` | A8 |  | D | `VOLSER` or `UNIT` is required in z/OS. Not for z/VSE.

## Additional Fields Supported for z/OS

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`EXPIRATION-DATE` | A8 |  | D |
`EXPIRATION-DATX` | D |  | D |
`RECFM` | A4 |  | D | Required.
`LRECL` | N5 |  | D | Required.
`BLKSIZE` | N5 |  | D | Required.
`ALLOCATION-TYPE` | A3 |  | D | Required.
`PRIMARY-ALLOCATION` | N10 |  | D | Required.
`SECONDARY-ALLOCATION` | N10 |  | D | Required.
`DISP` | A3 |  | D |
`DIRECTORY-BLOCKS` | N7 |  | D | Required for PO-type datasets (see `DSORG` field).
`CATALOG` | A3 |  | D |
`RLSE` | A3 |  | D |
`CONTIG` | A3 |  | D |
`ROUND` | A3 |  | D |
`EXTENDED-TEXT` | A250 | M/3 | D |
`VOLUME-COUNT` | N2 |  | D | Required if writing multiple reels
`VOLUME-SEQUENCE` | N2 |  | D |
`DENSITY` | A1 |  | D |
`LABEL` | A4 |  | D |
`DDNAME` | A8 |  | D |
`DSNTYPE` | A8 |  | D |
`DSNTYPE-VERSION` | N1 |  | D |
`EATTR` | A3 |  | D |
`FREE` | A3 |  | D |
`SMS-STORAGE-CLASS` | A8 |  | D |
`SMS-MANAGEMENT-CLASS` | A8 |  | D |
`SMS-DATA-CLASS` | A8 |  | D |
`MAXGENS` | N9 |  |  |

## Additional Fields Supported for z/VSE

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`EXPIRATION-DATE` | A8 |  | D |
`EXPIRATION-DATX` | D |  | D |
`EXTENT-START` | N10 |  | D | Required.
`EXTENT-SIZE` | N10 |  | D | Required.

## Additional Fields Supported for BS2000

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`SYSTEM-CODE` | B2 |  |  |
`RECFM` | A4 |  | D |
`LRECL` | N5 |  | D |
`BLKSIZE` | N5 |  | D |
`ALLOCATION-TYPE` | A4 |  | D |
`PRIMARY-ALLOCATION` | N10 |  | D |
`SECONDARY-ALLOCATION` | N10 |  | D |
`LABEL` | A4 |  | D |
`SHARE` | A3 |  | D |
`ISAM-KEY-POSITION` | N5 |  | D |
`ISAM-KEY-LENGTH` | N5 |  | D |
`REPLACE` | A3 |  | D |
`BLOCK-CONTROL` | A6 |  | D |
`PASSWORD` | A8 |  | D |
`PRODUCT` | A1 |  | D |
`VOLSER-ARRAY` | A6 | M / 5 | D |

## Relevant Error Codes

Code | Text | z/OS | z/VSE | BS2000
--- | --- | --- | --- | ---
530 | Access denied by Security Facility. | X |  | X
531 | Password missing or incorrect. |  |  | X
556 | File is in use. |  |  | X
565 | Syntax error in dataset name. |  |  | X
658 | Dataset is not cataloged. |  |  | X
659 | Dataset is already cataloged. |  |  | X
694 | Strange error opening VTOC. |  | X |
695 | VTOC is in use. |  | X |
696 | Cannot assign logical unit. |  | X |
699 | GETVIS storage request failed. |  | X |
700 | Invalid value specified (`DSORG`/`RECFM`/`TYPE`). |  |  | X
701 | `DSNAME` missing. | X | X | X
710 | Allocation failed. Reason=`TAPES NOT ALLOWED`. | X | X | X
733 | User ID does not exist. |  |  | X
798 | Task was not started under TSOS. |  |  | X
799 | Entire System Server internal error. |  |  | X
853 | Retention cycle unexpired `/ NEWNAME` exists. |  |  | X
878 | Volume defined as CA-Dynam/D pool name. |  | X |
899 | I/O error reading VTOC. |  | X |
981 | Invalid value specified (`BLKCTRL/BLKSIZE/LRECL`). |  |  | X
991 | Unknown product. |  |  | X
993 | Cannot open file. |  |  | X
994 | File not on volume. |  | X |
996 | Volume not online. |  | X |

## Field Descriptions

Field Name | Type/Length | Operating System
--- | --- | ---
`ALLOCATION-TYPE` | (A4) | z/OS, BS2000

Space allocation type. Possible values:

z/OS | BS2000
--- | ---
`BLK` | Block. | `NSTD` | Non-standard blocks (tape files).
`CYL` | Cylinder. | `PAM` | PAM pages (default).
`TRK` | Tracks (default). |

Field Name | Type/Length | Operating System
--- | --- | ---
BLKSIZE | (N5) | z/OS, BS2000

z/OS | BS2000
--- | ---
Block size. The default is 0. | Number of PAM pages for a block if the field `ALLOCATION-TYPE` is `PAM`. The default is 1.

For non-STD blocks, block size in bytes (only valid for tape files).

Field Name | Type/Length | Operating System
--- | --- | ---
`BLOCK-CONTROL` | (A6) | BS2000

Block control type for this file (depending on disk type K or NK). Possible options:

Option | Explanation
--- | ---
`DATA` | PAM key information in data (NK disks only)
`NO` | No PAM key information (NK disks only)
`PAMKEY` | Default. PAM key separate from data.

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

Specifies whether and how the dataset is cataloged. Possible options:

Option | Explanation
--- | ---
`NO` | Default. Dataset is not cataloged.
`YES` | Dataset is cataloged. If you specify generation dataset name (`DATASET(+1)`), the dataset is always cataloged. The dataset must already have been cataloged (see the view `CATALOG-UPDATE`, especially the field `NUMBER-OF-GENERATIONS`).

Field Name | Type/Length | Operating System
--- | --- | ---
`CONTIG` | (A3) | z/OS

Specifies contiguous allocated space. Possible options:

Option | Explanation
--- | ---
`NO` | Default. Space is not allocated contiguously.
`YES` | Space is allocated contiguously.

Field Name | Type/Length | Operating System
--- | --- | ---
`CREATE-JOBNAME` | (A8) | z/OS

Job name used to create the data set described by its format 8 DSCB.

Field Name | Type/Length | Operating System
--- | --- | ---
`CREATE-STEPNAME` | (A8) | z/OS

Step name used to create the data set described by its format 8 DSCB.

Field Name | Type/Length | Operating System
--- | --- | ---
`DDNAME` | (A8) | z/OS

Internal DD name used by the Entire System Server. It must be specified on calls to `READ-FILE` and `WRITE-FILE` when allocating tape units.

Field Name | Type/Length | Operating System
--- | --- | ---
`DSNTYPE` | (A8) | z/OS

The type of data set to be allocated. Possible values:

OptionValue | Explanation
--- | ---
`BASIC` | Basic format sequential data set (default).
`LARGE` | Large format sequential data set.
`LIBRARY` | Partitioned data set extended (PDSE).

Field Name | Type/Length | Operating System
--- | --- | ---
`DSNTYPE-VERSION` | (N1) | z/OS

The data set version number for a library (PDSE). Possible values are 1 or 2.

Field Name | Type/Length | Operating System
--- | --- | ---
`DENSITY` | (A1) | z/OS

Tape density. Possible options:

Option | Explanation
--- | ---
3 | 1600 BPI
4 | 6250 BPI

Field Name | Type/Length | Operating System
--- | --- | ---
`DIRECTORY-BLOCKS` | (N7) | z/OS

Number of directory blocks for PDS.

Field Name | Type/Length | Operating System
--- | --- | ---
`DISP` | (A3) | z/OS

Disposition of the dataset. Possible values:

Value | Explanation
--- | ---
`NEW` | Allocate new dataset.

Field Name | Type/Length | Operating System
--- | --- | ---
`DSNAME` | (A54) | z/OS, z/VSE , BS2000

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

Field Name | Type/Length | Operating System
--- | --- | ---
`DSORG` | (A4) | z/OS, z/VSE, BS2000

Dataset organization. Possible options:

z/OS | z/VSE | BS2000
--- | --- | ---
`PO` | Partitioned dataset (PDS). | `SD` | Default. Sequential dataset. | `ISAM` | Default. Indexed Sequential Access Method.
`PAM` | Block oriented file organization handled by User Primary Access Method (UPAM).
`PS` | Default. Sequential dataset. | `PLAM` | Program Library Access Method for LMS Libraries.
`SAM` | Sequential Access Method.

Field Name | Type/Length | Operating System
--- | --- | ---
`EATTR` | (A3) | z/OS

Extended attributes. Possible values:

Value | Explanation
--- | ---
`OPT` | Data set can support extended attributes (format 8 and 9 DSCBs).
`NO` | Data set does not support extended attributes (default).

Field Name | Type/Length | Operating System
--- | --- | ---
`EXPIRATION-DATE` | (A8) | z/OS, z/VSE

Expiration date in the format `YYDDD` or `YYYYDDD`. If `EXPIRATION-DATE` is specified with format `YYDDD`, it will be converted to the `YYYY/DDD` format using a fixed window from 1964 to 2063.

For z/OS, z/VSE, there is no default (i.e., no expiration date).

For BS2000, the default is the current date.

Field Name | Type/Length | Operating System
--- | --- | ---
`EXPIRATION-DATX` | (D) | z/OS, z/VSE

Expiration date in internal format.

Field Name | Type/Length | Operating System
--- | --- | ---
`EXTENDED-TEXT` | (A250) | z/OS

Text lines (up to 3) containing error description.

Field Name | Type/Length | Operating System
--- | --- | ---
`EXTENT-SIZE` | (N10) | z/VSE

Size of the extent.

Field Name | Type/Length | Operating System
--- | --- | ---
`EXTENT-START` | (N10) | z/VSE

Defines start of extent. For FBA, it is the block number. For CHD, it is the track number.

For allocating free space on any location, specify `EXTENT-START = -1`.

Field Name | Type/Length | Operating System
--- | --- | ---
`FREE` | (A3) | z/OS

Specify `YES` to free the allocation for DDNAME.

Field Name | Type/Length | Operating System
--- | --- | ---
`ISAM-KEY-LENGTH` | (N5) | BS2000

Gives the key length. Default is 8, maximum value is 253.

Field Name | Type/Length | Operating System
--- | --- | ---
`ISAM-KEY-POSITION` | (N5) | BS2000

Gives the position of the first byte of the key within the record.

Default: `5` for `RECFM=V`, `1` for `RECFM=F`.

Field Name | Type/Length | Operating System
--- | --- | ---
`LABEL` | (A4) | z/OS, BS2000

Type of label processing.

Field Name | Type/Length | Operating System
--- | --- | ---
`LRECL` | (N5) | z/OS, BS2000

Logical record length. The default is 0.

Field Name | Type/Length | Operating System
--- | --- | ---
`MAXGENS` | (N9) | z/OS

Maximum number of member generations for a PDSE version 2.

Possible values are 0 (no generations) or a value between 1 and the upper limit specified as MAXGENS_LIMIT in parmlib member IGDSMSxx.

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

Password for write access, if existing file must be replaced.

Field Name | Type/Length | Operating System
--- | --- | ---
`PRIMARY-ALLOCATION` | (N10) | z/OS, BS2000

- z/OS: Primary space allocation (default is 0).

- BS2000: Number of PAM pages for primary allocation (default is system default).

Field Name | Type/Length | Operating System
--- | --- | ---
`PRODUCT` | (A1) | BS2000

Access method used. Possible options:

- `M` = LMS (BS2000)

- `' '` = default

Provide the following fields to create an LMS PLAM library:

#### Example:

    FIND FILE-ALLOCATE WITH NODE = node
      AND DSNAME = 'dsname'
      AND DSORG = 'PLAM'
      AND PRODUCT = 'M'
      AND REPLACE = 'NO'
      ...

Field Name | Type/Length | Operating System
--- | --- | ---
`RECFM` | (A4) | z/OS, BS2000

Record format.

For z/OS, the default is `FB`.

For BS2000, the default is `V,N`.

Field Name | Type/Length | Operating System
--- | --- | ---
`REPLACE` | (A3) | BS2000

Specifies whether file with the same name is to be overwritten. Possible options:

Option | Explanation
--- | ---
`NO` | Default. Allocate only if file does not exist.
`YES` | Overwrite existing file.

The value `YES` is not possible for PLAM libraries.

Field Name | Type/Length | Operating System
--- | --- | ---
`RLSE` | (A3) | z/OS

Specifies whether unused space is released after the dataset is closed. Possible options:

Option | Explanation
--- | ---
`NO` | Default. Unused space is not released.
`YES` | Unused space is released after dataset is closed.

Field Name | Type/Length | Operating System
--- | --- | ---
`ROUND` | (A3) | z/OS

Specifies whether one or more whole cylinders are to be allocated. Possible options:

Option | Explanation
--- | ---
`NO` | Default. Allocated space need not be whole cylinders.
`YES` | Allocate one or more whole cylinders.

Field Name | Type/Length | Operating System
--- | --- | ---
`SECONDARY-ALLOCATION` | (N10) | z/OS, BS2000

z/OS: Secondary space allocation (default is 0).

BS2000: Number of PAM pages for secondary allocation (default is system default).

Field Name | Type/Length | Operating System
--- | --- | ---
`SHARE` | (A3) | BS2000

Defines whether a file can be shared. Possible options:

Option | Explanation
--- | ---
`NO` | Default. File cannot be shared.
`YES` | File can be shared.

Field Name | Type/Length | Operating System
--- | --- | ---
`SMS-DATA-CLASS` | (A8) | z/OS

Data class of SMS managed file.

Field Name | Type/Length | Operating System
--- | --- | ---
`SMS-MANAGEMENT-CLASS` | (A8) | z/OS

Management class of SMS managed file.

Field Name | Type/Length | Operating System
--- | --- | ---
`SMS-STORAGE-CLASS` | (A8) | z/OS

Storage class of SMS managed file.

Field Name | Type/Length | Operating System
--- | --- | ---
`UNIT` | (A8) | z/OS, BS2000

Generic unit name on which the dataset is to be allocated, for example, `SYSDA`.

For BS2000, this field is relevant only for tape files.

Field Name | Type/Length | Operating System
--- | --- | ---
`VOLSER` | (A6) | z/OS, z/VSE, BS2000

Volume serial number where the file is to be located.

In BS2000, for multi-volume tape files, use the field `VOLSER-ARRAY`.

Field Name | Type/Length | Operating System
--- | --- | ---
`VOLSER-ARRAY` | (A6) M5 | BS2000

For multi-volume tape file: list of maximum 5 volumes.

Field Name | Type/Length | Operating System
--- | --- | ---
`VOLUME-COUNT` | (N2) | z/OS

Maximum number of output volumes to be allocated. Required if writing multiple reels.

Field Name | Type/Length | Operating System
--- | --- | ---
`VOLUME-SEQUENCE` | (N2) | z/OS

When a tape dataset is cataloged, you can supply a value of greater than 1 if processing is not the start with the first reel.

### On this page

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