ALLOCATE command: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(53 intermediate revisions by 4 users not shown)
Line 16: Line 16:
</p>
</p>
   
   
<b>Where:</b>
Where:
<table>  
<table>  
<tr>
<tr>
Line 25: Line 25:
<tr>
<tr>
<th nowrap><var>LIKE</var> previousname</th>
<th nowrap><var>LIKE</var> previousname</th>
<td>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. <i>previousname</i> is the name of a previously defined data set.     
<td>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 <var>[[DEFINE_DATASET_command|DEFINE DATASET]]</var> command. <i>previousname</i> is the name of a previously defined data set.     
<p>
<p>
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.</p>
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.</p>
Line 35: Line 35:
USER is the default.</p>
USER is the default.</p>
<p>
<p>
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, <i>and</i> you can allocate only those types of data sets allowed by the current setting of the <var class="product">Model&nbsp;204</var> ALOCPRIV parameter.</p>
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, <i>and</i> you can allocate only those types of data sets allowed by the current setting of the <var>[[ALOCPRIV_parameter|ALOCPRIV]]</var> parameter.</p>
<p>
<p>
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.</p>
Data sets allocated with SCOPE=SYSTEM can be released (with the <var>[[FREE_command|FREE]]</var> 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.</p>
</td></tr>
</td></tr>
   
   
Line 62: Line 62:


==Examples==
==Examples==
====Example 1====
====Example 1: Using a template from DEFINE DATASET====
<p>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. </p>
<p>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 (<var>[[USE_command|USE]]</var>) data set with a name of OUTFILE, a scope of USER, and a data set name of M204.VEHICLES.REPORT. </p>
<p>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. </p>
<p>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. </p>
<p>The ALLOCATE command also creates an OUTFILE template that can be used in the LIKE phrase of another ALLOCATE or DEFINE DATASET command: </p>
<p>The ALLOCATE command also creates an OUTFILE template that can be used in the LIKE phrase of another ALLOCATE or DEFINE DATASET command: </p>
Line 74: Line 74:
</p>
</p>


====Example 2====
====Example 2: Using the WITH phrase to override template attributes====
<p>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. </p>
<p>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. </p>
<p>The cylinder and volume attributes are copied from the SAMPLE data set through the LIKE phrase. </p>
<p>The cylinder and volume attributes are copied from the SAMPLE data set through the LIKE phrase. </p>
Line 83: Line 83:
</p>
</p>


====Example 3====
====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:  
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:  
<p class="code">ALLOCATE OUTFILE WITH SCOPE=SYSTEM -  
<p class="code">ALLOCATE OUTFILE WITH SCOPE=SYSTEM -  
Line 92: Line 92:
</p>
</p>


====Example 4====
====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:  
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:  
<p class="code">DEFINE DATASET SAMPLE WITH SCOPE=SYSTEM -  
<p class="code">DEFINE DATASET SAMPLE WITH SCOPE=SYSTEM -  
Line 102: Line 102:
</p>
</p>


====Example 5====
====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):  
The following example allocates a tape data set that requires a scratch tape (because VOLUME is not specified):  
<p class="code">ALLOCATE TAPEFILE WITH SCOPE=SYSTEM -  
<p class="code">ALLOCATE TAPEFILE WITH SCOPE=SYSTEM -  
Line 109: Line 109:
</p>
</p>


====Example 6====
====Example 6: Allocating an in-memory file====
The following example allocates an [[In-memory files|in-memory file]] named BUSES:
The following example allocates an in-memory file named BUSES:
<p class="code">ALLOCATE BUSES WITH MEMORY PAGES=10000
<p class="code">ALLOCATE BUSES WITH MEMORY PAGES=10000
</p>
</p>
<p>The difference between using the ALLOCATE and DEFINE DATASET command for in-memory files is:</p>
For more information on usage, see [[#In-memory file allocation and restoration|In-memory file allocation and restoration]].
<ul>
For more information on in-memory files in general, see [[In-memory files]].
<li>
<p>For a DEFINE DATASET command the memory object is not allocated until the file is first opened or created.</p>
</li>
<li>
<p>For an ALLOCATE command the memory object is immediately allocated.</p>
</li>
</ul>
<p>
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.</p>
 
<p>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.</p>
 
<p>The [[DUMP command]] and [[RESTORE command]] can process in-memory files.</p>
<p class="note"><b>Note:</b> You cannot create in-memory files that are part of a multi-dataset file, such as the following:
<br/></p>
<p class="code">CREATE  FILE  filename  FROM  filenam1,filenam2
</p>


==Usage notes==
==Usage notes==
Line 169: Line 149:


====VSAM files====
====VSAM files====
<p>Although you can dynamically allocate an existing VSAM file to <var class="product">Model&nbsp;204</var> with ALLOCATE, you cannot dynamically allocate a new VSAM file to <var class="product">Model&nbsp;204</var>.</p>
<p>Although you can dynamically allocate an existing [[Accessing_BSAM_and_VSAM_files#VSAM_I.2FO_processing|VSAM]] file to <var class="product">Model&nbsp;204</var> with ALLOCATE, you cannot dynamically allocate a new VSAM file to <var class="product">Model&nbsp;204</var>.</p>


====Dynamic space allocation====
====Dynamic space allocation====
Line 175: Line 155:


====Allocation under external security interface====
====Allocation under external security interface====
<p>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 <var class="product">Model&nbsp;204</var> system manager and the installation's security officer for the security interface. For detailed information on security interfaces, refer to the <var class="book">Rocket Model&nbsp;204 Security Interfaces Manual</var>. </p>
<p>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 <var class="product">Model&nbsp;204</var> system manager and the installation's security officer for the security interface. For detailed information on security interfaces, refer to [[:Category:Security interfaces|Security interfaces]]. </p>


====Allocating large data sets====
====Allocating LARGE data sets====
<p>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.</p>
<p>
<p>You cannot yet allocate large checkpoint or journal data sets.</p>
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.</p>
<p>
LARGE CHKPOINT data sets are supported in Model 204 version 7.7 and later.</p>
<p class="note"><b>Note:</b> When dynamically allocating a pre-existing, LARGE dataset, make sure to use LARGE and SAM in the ALLOCATE command:
<ul>
<li>For non-Model 204, sequential files: <br />
<code>ALLOCATE OUTFILEA WITH OLD LARGE SAM DSN=OUTFILEA.M204</code></li>
<li>For Model 204 database files: <br />
<code>ALLOCATE MYM204DB WITH OLD LARGE SAM DSN=MYM204DB.M204</code></li>
</ul></p>


====Update units====
====Update units====
<p>When it processes ALLOCATE, <var class="product">Model&nbsp;204</var> ends any update unit in progress and begins a [[File_Integrity_and_Recovery#Non-backoutable_update_units|non-backoutable update unit]]. </p>
<p>
When it processes ALLOCATE, <var class="product">Model&nbsp;204</var> ends any update unit in progress and begins a [[File_integrity_and_recovery#Non-backoutable_update_units|non-backoutable update unit]]. </p>
 
====In-memory file allocation and restoration ====
<p>
The difference between using the ALLOCATE and DEFINE DATASET command for in-memory files is:</p>
<ul>
<li>For a DEFINE DATASET command the memory object is not allocated until the file is first opened or created.</li>
<li>For an ALLOCATE command the memory object is immediately allocated.</li>
</ul>
<p>
When you create an in-memory file, the default <var>[[FRCVOPT parameter|FRCVOPT]]</var> value is X'24', which means that this file does not participate in journal and checkpoint logging.</p>
 
<p>
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 <var>[[FOPT_parameter|FOPT]]</var>=0, which is [[Transaction_back_out|TBO]] enabled, and TBO is supported. <var>[[REGENERATE_command|REGENERATE]]</var> is also supported. <var>[[RESTART_command|RESTART]]</var> 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.</p>
 
<p>
The [[DUMP command]] and [[RESTORE command]] can process in-memory files.</p>
<p class="note"><b>Note:</b> You <strong>cannot</strong> create in-memory files that are part of a multi-dataset file, such as the following:</p>
<p class="code">CREATE  FILE  <i>filename</i>  FROM  <i>filenam1</i>, <i>filenam2</i>
</p>
For more information on in-memory files, see [[In-memory files]].


====Obsolete format====
====Obsolete format====
<p>The form of the ALLOCATE command discussed as follows is obsolete and is supplied only for reasons of compatibility.</p>
<p>
<p>Refer to the following form of the ALLOCATE command: </p>
The form of the ALLOCATE command discussed as follows is obsolete and is supplied only for reasons of compatibility.</p>
<p class="code">ALLOCATE <var class="term">ddname</var> <var class="term">dsname</var>  
<p>
Refer to the following form of the ALLOCATE command: </p>
<p class="syntax">ALLOCATE <span class="term">ddname</span> <span class="term">dsname</span>  
</p>
</p>
<p>The TIOT and XTIOT options cannot be specified.</p>
<p>
<p>If the <var class="term">ddname</var> prefix is TAPE or OUT, the ALLOCATE command assumes a sequential data set organization. The TIOT option is used.</p>
The TIOT and XTIOT options cannot be specified.</p>
<p>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.</p>
<p>
<p>The example below illustrates the ALLOCATE command just described followed by an equivalent ALLOCATE command that dynamically allocates data sets: </p>
If the <var class="term">ddname</var> prefix is TAPE or OUT, the ALLOCATE command assumes a sequential data set organization. The TIOT option is used.</p>
<p>
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.</p>
<p>
The example below illustrates the ALLOCATE command just described followed by an equivalent ALLOCATE command that dynamically allocates data sets: </p>
<p class="code">ALLOCATE VEHICLES M204.TEST.VEHICLES
<p class="code">ALLOCATE VEHICLES M204.TEST.VEHICLES
   
   
Line 205: Line 224:


==Processing Partitioned data sets==
==Processing Partitioned data sets==
<p>On z/OS systems only, <var class="product">Model&nbsp;204</var> 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 <var class="product">Model&nbsp;204</var> as input or output data set, in USE statements, or to process images. When you allocate a new PDS, <b>the parameters directory and member are required</b>. The PDS can be allocated either outside of <var class="product">Model&nbsp;204</var> dynamically or within <var class="product">Model&nbsp;204</var>. In the ALLOCATE command, you must use the keyword MEMBER or MEM. </p>
<p>
<p>The PDS option is required only when creating a new PDS data set, not when allocating a previously defined data set.</p>
On z/OS systems only, <var class="product">Model&nbsp;204</var> 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 <var class="product">Model&nbsp;204</var> as input or output data set, in USE statements, or to process images. When you allocate a new PDS, <b>the parameters directory and member are required</b>. The PDS can be allocated either outside of <var class="product">Model&nbsp;204</var> dynamically or within <var class="product">Model&nbsp;204</var>. In the ALLOCATE command, you must use the keyword MEMBER or MEM. </p>
<p>
The PDS option is required only when creating a new PDS data set, not when allocating a previously defined data set.</p>


====Syntax====
====Syntax====
<p class="syntax">[DSNAME=<i>name</i>] [MEMBER=PDS_<i>name</i>]
<p class="syntax">[DSNAME=<span class="term">name</span>] [MEMBER=PDS_<span class="term">name</span>]
</p>
</p>


Line 231: Line 252:
<p>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 -<var class="term">n</var> or +<var class="term">n</var> 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.</p>  
<p>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 -<var class="term">n</var> or +<var class="term">n</var> 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.</p>  
<ul>
<ul>
<li>For more information on GDGs and journaling, see the <var class="book">Rocket Model 204 System Manager's Guide.</var></li>
<li>For more information on GDGs and journaling, see [[Configuring checkpoint and journal data streams#Perpetual journaling for z/OS|Perpetual journaling for z/OS]]. </li>
<li>For a quick overview of GDGs, see the IBM z/OS concepts page:
 
http://publib.boulder.ibm.com/infocenter/zos/basics/index.jsp?topic=/com.ibm.zos.zconcepts/zconcepts_175.htm</li>
<li>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.</li>
 
<li>For complete information on the use of GDGs, see the IBM document, <i>z/OS DFSMS Using Data Sets</i> document number SC26-7410, "Chapter 29: Processing Generation Data Groups."</li>
<li>For complete information on the use of GDGs, see the IBM document, <i>z/OS DFSMS Using Data Sets</i> document number SC26-7410, "Chapter 29: Processing Generation Data Groups."</li>
</ul>
</ul>


====Creating a GDG base and Model DSCB data set====
====Creating a GDG base and Model DSCB data set====
<p>Before you can use the <var class="product">Model&nbsp;204</var> dynamic allocation feature for a GDG, you must create a GDG base.</p>
<p>
<p>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. </p>
Before you can use the <var class="product">Model&nbsp;204</var> dynamic allocation feature for a GDG, you must create a GDG base.</p>
<p>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.</p>
<p>
<p class="code">
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. </p>
//M204GDG EXEC PGM=IDCAMS  
<p>
You can create a model DSCB and the GDG's base using the following sample JCL. The model DSCB data set, in this case <code>DSN=SAMPLE.GDGDSNAM</code>, 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. </p>
<p class="code">//M204GDG EXEC PGM=IDCAMS  
//* DSN=SAMPLE.GDGDSNAM is the Model DSCB data set
//* DSN=SAMPLE.GDGDSNAM is the Model DSCB data set
//GDGDSCB DD DSN=SAMPLE.GDGDSNAM,DCB=(RECFM=FB,LRECL=80,BLKSIZE=800),  
//GDGDSCB DD DSN=SAMPLE.GDGDSNAM,DCB=(RECFM=FB,LRECL=80,BLKSIZE=800),  
Line 258: Line 282:
</p>
</p>
   
   
<b>Where:</b>
Where:
<table>  
<table>  
<tr>
<tr>
<th><var class="term">GDGCTL</var></th>
<td>GDGCTL</td>
<td> must be the same volume as that of the user catalog.</td>
<td>Must be the same volume as that of the user catalog.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var class="term">NAME</var></th>
<td>NAME</td>
<td> must be the same as the model DSCB DSN.</td>
<td>Must be the same as the model DSCB DSN.</td>
</tr>
</tr>
   
   
Line 273: Line 297:


====Creating a new GDG data set====
====Creating a new GDG data set====
<p>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.)</p>
<p>
To create a new GDG data set, use the <code>GEN=+1</code> keyword on <var>[[DEFINE DATASET command|DEFINE]]</var>/<var>ALLOCATE</var>. 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.) </p>


====Examples for GDG usage====
====Examples for GDG usage====
<ul>
<ul>
<li>
<li><var>DEFINE/ALLOCATE</var> a new generation of a GDG data set:
DEFINE/ALLOCATE a new generation of a GDG data set.
<p class="code">DEFINE DATASET OUTGDG WITH SCOPE=SYSTEM                -
<p class="code">DEFINE DATASET OUTGDG WITH SCOPE=SYSTEM                -
DSNAME=SAMPLE.GDGDSNAM LRECL=80 BLKSIZE=800            -
DSNAME=SAMPLE.GDGDSNAM LRECL=80 BLKSIZE=800            -
TRACK PRIMARY=5 SECONDARY=5 RECFM=FB GEN=+1 NEW CATALOG -
TRACK PRIMARY=5 SECONDARY=5 RECFM=FB GEN=+1 NEW CATALOG -
UNIT=DISK204 ALLOCATE OUTGDG
UNIT=DISK
ALLOCATE OUTGDG
FREE OUTGDG </p></li>


FREE OUTGDG
<li><var>DEFINE/ALLOCATE</var> 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 <code>OLD</code>:
</p>
<p>Failure to specify a DSCB in certain z/OS environments causes the following message to be displayed: </p>
<p class="code">M204.1069: ALLOCATE/FREE FAILED WITH RETURN CODE %C ERROR REASON CODE %C INFORMATION REASON CODE %C
</p>
</li>
<li>
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.
<p class="code">DEFINE DATASET OUTGDG WITH SCOPE=SYSTEM -
<p class="code">DEFINE DATASET OUTGDG WITH SCOPE=SYSTEM -
DSNAME=SAMPLE.GDGDSNAM GEN=+1 OLD ALLOCATE OUTGDG
DSNAME=SAMPLE.GDGDSNAM GEN=+1 OLD  
</p>
ALLOCATE OUTGDG
</li>
</p></li>
<li>
 
DEFINE/ALLOCATE a new generation data set with DCB information different than that of a previous generation of the GDG.
<li><var>DEFINE/ALLOCATE</var> a new generation data set with DCB information different than that of a previous generation of the GDG:
<p class="code">DEFINE DATASET OUTGDG2 WITH SCOPE=SYSTEM                -
<p class="code">DEFINE DATASET OUTGDG2 WITH SCOPE=SYSTEM                -
DSNAME=SAMPLE.GDGDSNAM LRECL=132 BLKSIZE=13200 RECFM=FB  -
DSNAME=SAMPLE.GDGDSNAM LRECL=132 BLKSIZE=13200 RECFM=FB  -
TRACK PRIMARY=15 SECONDARY=2 GEN=+2 NEW CATALOG          -
TRACK PRIMARY=15 SECONDARY=2 GEN=+2 NEW CATALOG          -
UNIT=SYSDA ALLOCATE OUTGDG2
UNIT=DISK
 
ALLOCATE OUTGDG2
DEFINE DATASET OUTGDG0 WITH SCOPE=SYSTEM                -
</p></li>
DSNAME=SAMPLE.GDGDSNAM GEN=0 OLD ALLOCATE OUTGDG0
</p>
</li>
</ul>
</ul>


====Conflicts with a second open GDG====
====Conflicts with a second open GDG====
<p>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.</p>
<p>
<p>If another <var class="product">Model&nbsp;204</var> job allocates a new GDG generation in the same GDG base file after the job starts, <var class="product">Model&nbsp;204</var>'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 <var class="product">Model&nbsp;204</var>.</p>
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.</p>
<p>For complete information on usage of GDGs see the IBM document, <i>z/OS DFSMS Using Data Sets</i> document number SC26-7410, "Chapter 29: Processing Generation Data Groups."</p>
<p>
 
If another <var class="product">Model&nbsp;204</var> job allocates a new GDG generation in the same GDG base file after the job starts, <var class="product">Model&nbsp;204</var>'s allocation is not updated and no longer has the correct current generation number. Issuing <var>FREE</var> and <var>ALLOCATE</var> 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 <var class="product">Model&nbsp;204</var>. </p>
====Creating a new GDG data set====
<p>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.</p>
<p>Failure to specify EXCLUSIVE on the ALLOCATE command causes a default to SHARE and the following message is displayed:</p>
<p class="code">M204.1069 ALLOCATE/FREE FAILED RETURN CODE 12 ERROR REASON CODE 0394
</p>
<p>Failure to specify DSCB in certain z/OS environments causes the following message to be displayed: </p>
<p class="code">M204.1069 ALLOCATE/FREE FAILED RETURN CODE 4 ERROR REASON CODE 048C
</p>
<p><b>Example 1: Building a GDG base file</b></p>
<p class="code">//JS0010 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
  DEFINE GENERATIONDATAGROUP (NAME(SAMPLE.TESTGDG) -
        NOSCRATCH LIMIT(5) EMPTY)
//*
</p>
 
====Example 2: Creating a specific model DSCB for one GDG====
<p class="code">//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
</p>
<p class="note"><b>Note:</b> You can combine the two steps into one step by adding the ALCDSCB0 DD statement to the IDCAMS step.</p>


[[Category: System administrator commands]]
[[Category: System administrator commands]]
[[Category: General user commands]]
[[Category: User commands]]
[[Category:Commands]]
[[Category:Commands]]

Latest revision as of 16:23, 4 February 2019

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.

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.