FILE-ALLOCATE

File 9
Op-Sys z/OS, z/VSE, BS2000/OSD
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/OSD

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

Space allocation type. Possible values:

z/OS BS2000/OSD
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/OSD
z/OS BS2000/OSD
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/OSD

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
1600 BPI
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/OSD

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

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

Dataset organization. Possible options:

z/OS z/VSE BS2000/OSD
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/OSD, 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/OSD

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

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

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

Type of label processing.

Field Name Type/Length Operating System
LRECL (N5) z/OS, BS2000/OSD

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

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

Field Name Type/Length Operating System
PRIMARY-ALLOCATION (N10) z/OS, BS2000/OSD
  • z/OS: Primary space allocation (default is 0).

  • BS2000/OSD: Number of PAM pages for primary allocation (default is system default).

Field Name Type/Length Operating System
PRODUCT (A1) BS2000/OSD

Access method used. Possible options:

  • M = LMS (BS2000/OSD)

  • ' ' = 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/OSD

Record format.

For z/OS, the default is FB.

For BS2000/OSD, the default is V,N.

Field Name Type/Length Operating System
REPLACE (A3) BS2000/OSD

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

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

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

Field Name Type/Length Operating System
SHARE (A3) BS2000/OSD

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

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

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

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

Volume serial number where the file is to be located.

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

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

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.