FILE-ALLOCATE

File	9
Op-Sys	z/OS, z/VSE, BS2000
Statement	`PROCESS`
Task	Enables the allocation of files from a Natural session.

Common Fields for all Operating Systems

Dictionary Field Name	F/L	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	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
`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.
`PO`	Partitioned dataset (PDS).			`PAM`	Block oriented file organization handled by User Primary Access Method (UPAM).
`PS`	Default. Sequential dataset.			`PLAM`	Program Library Access Method for LMS Libraries.
`PS`	Default. Sequential dataset.			`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.