ALLOCATE command

Dynamically allocate data sets for IBM z/OS and IBM 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 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 the DEFINE DATASET command.

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: Using a template from DEFINE DATASET

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: Using the WITH phrase to override template attributes

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: Using ALLOCATE without a DEFINE DATASET template

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: Using a DEFINE DATASET template, then ALLOCATE

The following example shows how the user can provide all the necessary attributes for allocation with the DEFINE DATASET command, 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: Allocating a tape data set

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: Allocating an in-memory file

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

ALLOCATE BUSES WITH MEMORY PAGES=10000

For more information on usage, see In-memory file allocation and restoration. For more information on in-memory files in general, see In-memory files.

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. ALLOCATE 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 DATASET command.

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 Security interfaces.

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 (greater than 65,535 tracks) data set if running under z/OS 1.7 or later.

LARGE CHKPOINT data sets are supported in Model 204 version 7.7 and later.

Note: When dynamically allocating a pre-existing, LARGE dataset, make sure to use LARGE and SAM in the ALLOCATE command:

• For non-Model 204, sequential files:
  ALLOCATE OUTFILEA WITH OLD LARGE SAM DSN=OUTFILEA.M204
• For Model 204 database files:
  ALLOCATE MYM204DB WITH OLD LARGE SAM DSN=MYM204DB.M204

Update units

When it processes ALLOCATE, Model 204 ends any update unit in progress and begins a non-backoutable update unit.

In-memory file allocation and restoration

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 value is X'24', which means that this file does not participate in journal and checkpoint logging.

However, remember that restoring an in-memory file with RESTORE from a backup will copy the FRCVOPT from that backup copy into the in-memory file, thus overriding the default. In-memory files are also created with FOPT=0, which is TBO enabled, and TBO is supported. REGENERATE is also supported. RESTART recovery is not supported. Given these caveats, if you want to provide for both REGENERATE recovery and TBO, the best parameter settings for in-memory files are FRCVOPT=X’20’ and FOPT=0.

The DUMP command and RESTORE command 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

For more information on in-memory files, see In-memory files.

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 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: If 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 (GDG) data sets

On z/OS systems only, you can create or access a generation data group (GDG) data set by using the GEN keyword with a 0 or -n or +n value under the ALLOCATE DATASET command. You can use GDG data sets for sequential I/O, in USE statements, to process images, or as data set files.

• For more information on GDGs and journaling, see Perpetual journaling for z/OS.
• For a quick overview of GDGs, go to the IBM z/OS information center at http://publib.boulder.ibm.com/infocenter/zos/basics/topic/com.ibm.zos.zbasics/lcmain.html and search for generation data group or GDG.
• For complete information on the use of GDGs, see the IBM document, z/OS DFSMS Using Data Sets document number SC26-7410, "Chapter 29: Processing Generation Data Groups."

Creating a GDG base and Model DSCB data set

Before you can use the Model 204 dynamic allocation feature for a GDG, you must create a GDG base.

Model DSCB (Data Set Control Block) data sets are, in most cases, no longer required. However, the example below shows how to allocate one if required.

You can create a model DSCB and the GDG's base using the following sample JCL. The model DSCB data set, in this case DSN=SAMPLE.GDGDSNAM, 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 //* DSN=SAMPLE.GDGDSNAM is the Model DSCB data set //GDGDSCB DD DSN=SAMPLE.GDGDSNAM,DCB=(RECFM=FB,LRECL=80,BLKSIZE=800), // VOL=SER=GDGCTL,SPACE=(TRK,0),UNIT=DISK //SYSPRINT DD SYSOUT=A //* DEFINE GDG defines the base GDG using the same name as the Model DSCB data set //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.

Creating a new GDG data set

To create a new GDG data set, use the GEN=+1 keyword on DEFINE/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 previous example.)

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=DISK ALLOCATE OUTGDG FREE OUTGDG

• 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=DISK ALLOCATE OUTGDG2

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.