ALLOCATE command

Dynamically allocate data sets for z/OS and z/VM

Summary

Privileges

System administrator or user

Function

Dynamically allocates a new or existing Model 204 data set, or non-Model 204 data set, and optionally the attributes of the data set. The ALLOCATE command also creates a data set definition at allocation time and deletes it if the definition was previously defined. This command applies only to z/OS and z/VM.

Syntax

ALLOCATE [DATASET] name [LIKE previousname] [WITH [SCOPE={USER | SYSTEM}] [[,] option...]

Where:

name	The name that would appear on a DD or FILEDEF statement for a new or existing data set.
LIKE previousname	The data set that the user is currently allocating the attributes of a previously defined data set or template. It copies the attributes of another data set or template named by a previous ALLOCATE or DEFINE DATASET command. previousname is the name of a previously defined data set. Used by itself, the LIKE phrase copies all the attributes of the previously defined data set. When WITH is used, the options listed in the WITH phrase dynamically override the attributes of the data set specified by the LIKE phrase. The data set name must be unique when the WITH phrase is present.
SCOPE	Refers more to the range of data set types that you can allocate (and release) than it does to the range of accessibility of the data set you are allocating. Regardless of the value of SCOPE, any data set allocated under Model 204 is accessible to any Model 204 user. USER is the default. You need system administrator or User 0 privileges to use the SYSTEM option of SCOPE. Without these privileges, you can only use USER or allow SCOPE to default to USER, and you can allocate only those types of data sets allowed by the current setting of the Model 204 ALOCPRIV parameter. Data sets allocated with SCOPE=SYSTEM can be released (with the FREE command) only by users with system administrator or User 0 privileges. Data sets allocated with SCOPE=USER can be released by any user, depending on the setting of ALOCPRIV.
options	These options are identical to the options described for DEFINE DATASET.

Syntax notes

Using LIKE

If a data set or template created with ALLOCATE is released by a FREE command, you cannot successfully reference it with a LIKE phrase. However, if a data set or template is created by DEFINE DATASET, allocated with ALLOCATE, and then released by FREE, you can successfully reference it with a LIKE phrase.

Checking for the OLD option

Before performing an allocation request, Model 204 checks:

• Whether a valid DSNAME is specified. If an OLD or APPEND option is specified, no further checking is done and Model 204 attempts the allocation.

• Whether the OLD option is specified. If this option is not indicated, the ALLOCATE command must specify the PRIMARY option. Under z/VM, the VOLUME option is also required.

Examples

Example 1

The following example shows how the ALLOCATE command can be used to refer to a template previously created by the DEFINE DATASET command. The ALLOCATE command allocates a new (USE) data set with a name of OUTFILE, a scope of USER, and a data set name of M204.VEHICLES.REPORT.

The LIKE phrase gives the OUTFILE data set some attributes of the SAMPLE data set created by the DEFINE DATASET command, namely a fixed block record format with a record length of 80 and a block size of 800, a data type organization of sequential, and a size of one cylinder on volume RPG001.

The ALLOCATE command also creates an OUTFILE template that can be used in the LIKE phrase of another ALLOCATE or DEFINE DATASET command:

DEFINE DATASET SAMPLE WITH SCOPE=SYSTEM - LRECL=80 BLKSIZE=800 RECFM=FB SEQUENTIAL - PRIMARY=1 CYLINDER VOLUME=RPG001 ALLOCATE OUTFILE LIKE SAMPLE - WITH DSNAME=M204.VEHICLES.REPORT

Example 2

The following example uses the WITH phrase of an ALLOCATE command to override attributes of a template referred to by the LIKE phrase. The ALLOCATE command allocates a data set with a name of VEHICLES and a size of one cylinder on volume RPG001.

The cylinder and volume attributes are copied from the SAMPLE data set through the LIKE phrase.

The WITH phrase, overriding attributes of the SAMPLE template, specifies a scope of USER, an undefined record format, a record length of 6184, and a data organization of direct. The WITH phrase is also used to define a new attribute, a data set name of M204.TEST.VEHICLES:

ALLOCATE VEHICLES LIKE SAMPLE - WITH DSNAME=M204.TEST.VEHICLES, RECFM=U - LRECL=6184 DIRECT

Example 3

The following example illustrates how the user can provide all the necessary attributes for a data set through the ALLOCATE command without referring to a DEFINE DATASET template:

ALLOCATE OUTFILE WITH SCOPE=SYSTEM - LRECL=80 BLKSIZE=800 RECFM=FB - SEQUENTIAL PRIMARY=1 - CYLINDER VOLUME=RPG001 - DSNAME=M204.VEHICLES.REPORT

Example 4

The following example shows how the user can provide all the necessary attributes for allocation with the DEFINE DATASET command, and then use only the ALLOCATE command and data set or template name to perform the allocation:

DEFINE DATASET SAMPLE WITH SCOPE=SYSTEM - LRECL=80 BLKSIZE=80 RECFM=F SEQUENTIAL - PRIMARY=1 CYLINDER VOLUME=RPG001 - DSNAME=M204.VEHICLES.REPORT ALLOCATE SAMPLE

Example 5

The following example allocates a tape data set that requires a scratch tape (because VOLUME is not specified):

ALLOCATE TAPEFILE WITH SCOPE=SYSTEM - DSN=MODEL204.JOURNAL.COPY UNIT=TAPE - DENSITY=1600 LABEL=NL

Example 6

The following example allocates an in-memory file named BUSES:

ALLOCATE BUSES WITH MEMORY PAGES=10000

The difference between using the ALLOCATE and DEFINE DATASET command for in-memory files is:

• For a DEFINE DATASET command the memory object is not allocated until the file is first opened or created.

• For an ALLOCATE command the memory object is immediately allocated.

When you create an in-memory file, the default FRCVOPT is X'24', which means that this file does not participate in journal and checkpoint logging. The DUMP and RESTORE commands can process in-memory files.

Note: You cannot create in-memory files that are part of a multi-dataset file, such as the following:

CREATE FILE filename FROM filenam1,filenam2

Usage notes

The ALLOCATE command dynamically allocates a new or existing Model 204 data set, or non-Model 204 data set, and optionally specifies the attributes of the data set. The ALLOCATE command also creates a data set definition at allocation time and deletes it if the definition was previously defined. This command applies only to z/OS and z/VM.

The ALLOCATE command lets you:

• Allocate new and existing data sets at run time. Data sets no longer have to be in the Model 204 startup deck for use during the run.

• Indicate the attributes, such as the DSNAME and SHARE/EXCLUSIVE options, that the operating system needs to create the data set.

• Refer to a template of attributes created by a DEFINE DATASET command. This template can contain some or all of the attributes required for allocation.

• Dynamically override a template's attributes or create new attributes.

• Provide all the allocation attributes for a data set without referring to a DEFINE DATASET template.

Who can issue an ALLOCATE command

Only User 0 can issue an ALLOCATE command for data sets with the prefix CCA. The system administrator can allocate all other types of data sets. The ALOCPRIV parameter determines the kinds of data sets that a user without system administrator privileges can allocate. An allocated data set is released through the FREE command.

Only a system administrator can issue an ALLOCATE command that simply specifies a data set. For example:

ALLOCATE SAMPLE

The data set specified must have all its allocation attributes defined by a previous DEFINE DATASET command, with SYSTEM the required value for the scope of the data set.

VSAM files

Although you can dynamically allocate an existing VSAM file to Model 204 with ALLOCATE, you cannot dynamically allocate a new VSAM file to Model 204.

Dynamic space allocation

Dynamic space allocation is supported under z/OS. For information on the options and uses of this feature, refer to "DEFINE data set: data set or file characteristics".

Allocation under external security interface

In an external security interface environment, all dynamic allocation services are subject to the particular environment's rules for data set validation. For example, the allocation of data sets can be restricted to allow only certain data set name patterns to be created on certain predefined volumes. The rules for data set access are determined by the Model 204 system manager and the installation's security officer for the security interface. For detailed information on security interfaces, refer to the Rocket Model 204 Security Interfaces Manual.

Allocating large data sets

The ALLOCATE command creates a data set definition at allocation time and deletes it if the definition was previously defined. You can define a large data set in only z/OS 1.7 or later.

You cannot yet allocate large checkpoint or journal data sets.

Update units

When it processes ALLOCATE, Model 204 ends any update unit in progress and begins a non-back outable update unit. For more information about Model 204 update units, see the Model 204 File Manager's Guide.

Obsolete format

The form of the ALLOCATE command discussed as follows is obsolete and is supplied only for reasons of compatibility.

Refer to the following form of the ALLOCATE command:

ALLOCATE ddname dsname

The TIOT and XTIOT options cannot be specified.

If the ddname prefix is TAPE or OUT, the ALLOCATE command assumes a sequential data set organization. The TIOT option is used.

Otherwise, the command assumes a direct data set organization. The default for the scope parameter is SYSTEM, that is, the scope of the allocation applies to all users. Specifying a scope of SYSTEM requires system administrator privileges. Either the TIOT or the XTIOT argument is used, depending on the setting of the SYSOPT2 parameter.

The example below illustrates the ALLOCATE command just described followed by an equivalent ALLOCATE command that dynamically allocates data sets:

ALLOCATE VEHICLES M204.TEST.VEHICLES ALLOCATE VEHICLES WITH SCOPE=SYSTEM - DSNAME=M204.TEST.VEHICLES OLD DIRECT ALLOCATE OUTFILE M204.OUTFILE ALLOCATE OUTFILE WITH SCOPE=SYSTEM - DSNAME=M204.OUTFILE OLD SEQUENTIAL

Processing Partitioned data sets

On z/OS systems only, Model 204 users can use a member of a Partitioned Data Set (PDS) as an input or output data set for physical sequential access. PDS data sets can be used in Model 204 as input or output data set, in USE statements, or to process images. When you allocate a new PDS, the parameters directory and member are required. The PDS can be allocated either outside of Model 204 dynamically or within Model 204. In the ALLOCATE command, you must use the new keyword MEMBER or MEM.

The PDS option is required only when creating a new PDS data set, not when allocating a previously defined data set.

Syntax

[DSNAME=name] [MEMBER=PDS_name]

Appending data to a PDS

You cannot append data to the end of a PDS member. Specifying the APPEND parameter for an existing member results in an ABEND. A system completion code of B14 and a return code of 4, generated when the data set is closed, indicates a duplicate name was found. The same error occurs if you specify DISP=MOD on the DD statement for a PDS member. You can expect the APPEND parameter on the ALLOCATE command to have no effect when opening for output a new member of a PDS, as long as no other errors occur.

If you specify all parameters on the ALLOCATE command, then a DEFINE DATASET command is not necessary.

Note: no member name is provided for an existing partitioned data set, then a data set is treated as sequential and all existing members are erased.

Output conflicts between open PDS members

When a PDS member is open for output, an exclusive enqueue with SCOPE=SYSTEM, QNAME=SPFEDIT, and RNAME=DATASET_NAME is obtained. For a given PDS, only one PDS member can be open for output at a time using one or multiple Model 204 Onlines.

Any attempt to open the same or another member of an already open-for-output PDS fails. The following message is issued to requestor(s) in the same or different Model 204 Online, because the file is already open for output by the same or a different Model 204 Online:

M204:0196 DATA SET dsn USED BY ddname DD STATEMENT CURRENTLY IN USE

TSO users can edit PDS members from data sets opened for output by Model\ 204, but until the data set is closed, attempts to write members back fail with the operating system message:

RESERVE FAILED

Any user who opens a PDS member for output prevents all other users from updating any other member in the same PDS until the data set is closed. To prevent long delays in updating PDS members, User Language programs should do a minimum of processing and avoid user input or output between OPEN and CLOSE statements or any other statements that might lead to an unpredicted wait time.

Processing generation data group data sets (GDG)

On z/OS systems only, Model 204 users can access any previously created GDG data set by using the GEN keyword with a 0 or n or +n value under ALLOCATE DATASET command. OLD must also be specified. You can use GDG data sets for sequential I/O, in USE statements, to process images, or as data set files.

Syntax

[DSNAME=name] [GEN={ -n | 0 | +n } OLD

Due to the nature of dynamic allocation (SVC99), however, an allocation of a GDG data set for input or output refers to the same data set for the duration of the job or Online session, even if generations are added to the GDG.

Creating a Data Set Control Block (DSCB)

Before using the Model 204 dynamic allocation feature for a GDG, a model Data Set Control Block (DSCB) and the base data set must be created.

You can create a model DSCB and the GDG's base using the following sample JCL. The DSCB must reside on the same volume as the catalog for the high-level qualifier, and the DSCB name and GDG base name must be the same.

//M204GDG EXEC PGM=IDCAMS //GDGDSCB DD DSN=SAMPLE.GDGDSNAM, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=800), // VOL=SER=GDGCTL,SPACE=(TRK,0),UNIT=DISK //SYSPRINT DD SYSOUT=A //SYSIN DD * DEFINE GDG (- NAME(SAMPLE.GDGDSNAM) - NOEMPTY - SCRATCH - LIMIT(5)) /* //

Where:

GDGCTL	must be the same volume as that of the user catalog.
NAME	must be the same as the model DSCB DSN.

The related keywords to allow processing and dynamic allocation of GDG data sets in z/OS are:

Keyword	Value	Comment
GEN=	0	Indicates a GDG data set number.
	+1	Use the option NEW when GEN=+n and this data set is created for the first time. NEW indicates a new generation member, not a new GDG. Use the option CATALOG to assure access to the intended generation through the system facilities when referencing a previously allocated (0, -n) generation member.
	-1	Use the option OLD to indicate that the data set already exists.

Examples for GDG usage

DEFINE/ALLOCATE a new generation of a GDG data set.

DEFINE DATASET OUTGDG WITH SCOPE=SYSTEM - DSNAME=SAMPLE.GDGDSNAM LRECL=80 BLKSIZE=800 - TRACK PRIMARY=5 SECONDARY=5 RECFM=FB GEN=+1 NEW CATALOG - UNIT=DISK204 ALLOCATE OUTGDG FREE OUTGDG

Failure to specify a DSCB in certain z/OS environments causes the following message to be displayed:

M204.1069: ALLOCATE/FREE FAILED WITH RETURN CODE %C ERROR REASON CODE %C INFORMATION REASON CODE %C

DEFINE/ALLOCATE a generation data set previously allocated in this job step. This is not a +2 generation but the same +1 generation previously allocated, freed and now reallocated as OLD.

DEFINE DATASET OUTGDG WITH SCOPE=SYSTEM - DSNAME=SAMPLE.GDGDSNAM GEN=+1 OLD ALLOCATE OUTGDG

DEFINE/ALLOCATE a new generation data set with DCB information different than that of a previous generation of the GDG.

DEFINE DATASET OUTGDG2 WITH SCOPE=SYSTEM - DSNAME=SAMPLE.GDGDSNAM LRECL=132 BLKSIZE=13200 RECFM=FB - TRACK PRIMARY=15 SECONDARY=2 GEN=+2 NEW CATALOG - UNIT=SYSDA ALLOCATE OUTGDG2 DEFINE DATASET OUTGDG0 WITH SCOPE=SYSTEM - DSNAME=SAMPLE.GDGDSNAM GEN=0 OLD ALLOCATE OUTGDG0

Conflicts with a second open GDG

Due to the nature of dynamic allocation (SVC99), however, an allocation of a GDG data set for input refers to the same data set for the duration of the job or Online session, even if generations are added to the GDG.

If another Model 204 job allocates a new GDG generation in the same GDG base file after the job starts, Model 204's allocation is not updated and no longer has the correct current generation number. Issuing FREE and ALLOCATE commands does not alter this behavior. The Online session or job must be recycled to reflect the current GDG base catalog structure for GDG input. To avoid such problems, allocate a GDG once per GDG base file in any run of Model 204.

For complete information on usage of GDGs see the IBM document, z/OS DFSMS Using Data Sets document number SC26-7410, "Chapter 29: Processing Generation Data Groups."

Creating a new GDG data set

To create a new GDG data set, use the GEN=+1 keyword on ALLOCATE. The GDG base file must have been built previously using IDCAMS, and, if required by your level of z/OS, a model DSCB must be provided. (To create a GDG base file and model DSCB, see the following examples.) You must specify EXCLUSIVE for the ALLOCATE command.

Failure to specify EXCLUSIVE on the ALLOCATE command causes a default to SHARE and the following message is displayed:

M204.1069 ALLOCATE/FREE FAILED RETURN CODE 12 ERROR REASON CODE 0394

Failure to specify DSCB in certain z/OS environments causes the following message to be displayed:

M204.1069 ALLOCATE/FREE FAILED RETURN CODE 4 ERROR REASON CODE 048C

Example 1: Building a GDG base file

//JS0010 EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE GENERATIONDATAGROUP (NAME(SAMPLE.TESTGDG) - NOSCRATCH LIMIT(5) EMPTY) //*

Example 2: Creating a specific model DSCB for one GDG

//JS0010 EXEC PGM=IEFBR14 //*ALLOCATE SPECIFIC MODEL DSCB FOR ONE GDG; //*HAS TO BE UNCATALOGUED, //*AND ON SAME PACK AS USERCAT FOR GDG BASE CATALOG ENTRY; //*IN THIS EXAMPLE, USERCAT FOR ALIAS 'SAMPLE' IS ON DSK123 //ALCDSCB0 DD DSN=SAMPLE.TESTGDG, // DISP=(,KEEP,DELETE), DO NOT CATLG // SPACE=(TRK,(0)), //*ANY DCB ATTRIBUTE MAY BE OVERRIDDEN IN DEFINE OR //*ALLOCATE // DCB=(LRECL=80,RECFM=FB), // UNIT=3380,VOL=SER=DSK123

Note: You can combine the two steps into one step by adding the ALCDSCB0 DD statement to the IDCAMS step.