DEFINE DATASET command

Summary

Privileges

System administrator

Function

Specifies characteristics of a Model 204 data set or file, or a non-Model 204 file such as a VSAM file or a basic sequential file

Syntax

DEFINE DATASET name [LIKE other-name] WITH SCOPE=SYSTEM options

Where options are one or more of the following:

[ALX | MXIG | CONTIG] [APPEND | NOAPPEND] [BLKSIZE=n] [BLOCK | TRACK | CYLINDER] [BUFNO=n] [CATALOG | NOCATALOG] [CLOSE={EOJ | NOUSERS}] [DATALEN=n] [DCLASS] [DDNAME=name | FILENAME=name] [DEFER] [DENSITY=n] [DIRECTORY=n] [DSNAME=name] [EATTR] [GDGRECNT] [GEN] [LABEL=label] [LARGE] [LRECL=n] [MCLASS] [MEMBER=member-name] [MEMORY] [NCP=n] [NEW | OLD | COND] [PASSWORD=password] [PAGES=n] [PDS] [PDSE] [POSITION=n] [PRIMARY=n] [RECFM=format] [RELEASE | NORELEASE] [RETENTION=n] [RETRYALLOC=n] [RETRYTIME=n] [ROUND] [SAM | VSAM | DAM] [SCLASS] [SECONDARY=n] [SEQUENTIAL | KEYED | KEYED SEQUENTIAL | DIRECT | SAM | VSAM | DAM] [SHARE | EXCLUSIVE] [SMSLIKE=dsn] [STRINGS=n] [TIOT| [XTIOT DIRECT OLD]] [UNIT=unit] [VOLMAX=n] [VOLSEQ=n] [VOLUME=volume]

Where:

The options for the command are defined in the table below. Certain options are meaningful only during the dynamic allocation of sequential data sets and are ignored during open processing. Because dynamic allocation is valid only under z/OS and z/VM, these options therefore are ignored under other operating systems.

DEFINE DATASET options

Option	Meaning
ALX or MXIG or CONTIG	ALX allocates up to five contiguous primary size areas on a new allocation. MXIG allocates the largest contiguous area as first extent on a new allocation. CONTIG specifies that all storage must be contiguous on a new allocation.
APPEND or NOAPPEND	Determines whether a data set is overwritten by new records. The APPEND option causes the file to be positioned after the last record each time the file is opened. The NOAPPEND option specifies that the data set is overwritten. The default is NOAPPEND. This option is not supported under z/VSE.
BLKSIZE	Specifies the maximum length (in bytes) of a data block. The range of acceptable values is 0 to 32767. 0 indicates that a value has not been specified, and is the default. When using the BLOCK parameter, you must specify BLKSIZE. If the record format is F, the block size must be a multiple of the logical record length. If the record format is V, the block size must equal the maximum value and be at least four bytes larger than the logical record length. This option applies only to non-Model 204 files.
BLOCK/ TRACK/ CYLINDER	Determines the type of space allocation. The BLOCK option allocates space by the BLKSIZE of actual data multiplied by the value of the PRIMARY option. TRACK allocates space in tracks and CYLINDER allocates space in cylinders. BLOCK can be abbreviated as BLK and TRACK can be abbreviated as TRK. These options apply only to new data sets that are to be allocated dynamically.
BUFNO	Indicates whether the Multiple Buffers feature is used. BUFNO is the number of buffers that Model 204 allocates for this data set during output. To invoke multiple buffering, the value of BUFNO must be greater than one. The internal buffering logic requires that BUFNO's value be at least one greater than the value of the NCP parameter. If the requested BUFNO is not at least one greater than NCP, the open exit routine forces BUFNO to a value one greater than NCP. BUFNO's default value is one, which disables the multiple buffering feature. See the NCP option later in this table for related information.
CATALOG or NOCATALOG	(Only z/OS.) Determines whether an index entry is created in a system catalog. The CATALOG option specifies that the system creates an index entry in a system catalog that points to the data set. Once the data set is cataloged, you can retrieve it in later jobs by entering a disposition other than NEW for the data set name. The NOCATALOG option specifies that an index entry is not created in the system catalog, although the data set is still retained by the system. To use the data set in future sessions, you must supply the VOLUME where the data set is located. The default is CATALOG. The data set is still cataloged if there is a system ABEND. The CATALOG/NOCATALOG options are meaningful only during dynamic allocation of new data sets under 0S/390. They are ignored under z/VM.
CLOSE	Specifies when to physically close a VSAM file. Options are NOUSERS and EOJ. NOUSERS indicates that the VSAM file is closed when no users are accessing the file. The default option is NOUSERS. EOJ indicates that the VSAM file is closed only during Model 204 system termination. This option is used for non-Model 204 files.
DATALEN	Specifies the length of the data portion of the records in a sequential data set. The values of the LRECL and BLKSIZE options are affected if you specify this option. The range of acceptable values is 0 to 32767. This option applies only to sequential data sets such as USE data sets and does not apply to Model 204 files. DATALEN is ignored during allocation time but overrides the LRECL option at open time if values for both LRECL and DATALEN are specified. Refer to the discussion of sequential data set open processing in Sequential I/O processing.
DCLASS	(Only z/OS.) Designates system manager storage SMS data class allocation.
DDNAME or FILENAME	Specifies the name (for disk files) or, under z/VSE, the unit number (for tape or unit record devices) in the JCL associated with this data set. This option is generally used with z/VSE. The maximum length of this option is 8. If this option is not indicated, Model 204 uses the name keyword specified in the DEFINE command. This name is the internal Model 204 name of the sequential data set or Model 204 file being described. It can also represent the template name. The name can be 1 to 8 characters. Generally, under z/VSE, it is translated to a 7-character file name that has been specified on a DLBL or TLBL statement.
DEFER	Defers mount requests until an OPEN command is issued.
DENSITY	Specifies the density with which a tape data set is written. If the DENSITY option is not specified, the highest density that the tape drive can support is used for output. This option is ignored for input, where Model 204 automatically determines the density (bpi) at which the tape it is reading was written. Acceptable values are 800, 1600, and 6250. This option applies only to dynamic allocation of tape data sets, which is valid only under z/OS.
DIRECTORY	Specifies the number of PDS directory blocks on a new allocation. The NEW parameter is required.
DSNAME	Specifies the name of the data set to the operating system. The maximum length is 44 characters. Most installations have data set naming conventions. Check with your system administrator for the valid data set names.
EATTR	(Only z/OS.) Enables a data set to be allocated on an EAV (Extended Address Volumes) volume, which contains more than 64K cylinders. You can allocate and use Model 204 database files and checkpoint, CCAJRNL, CCAJLOG, and USE data sets on EAV volumes above the 64K cylinder boundary. Both IOS Branch Entry (XMEMOPT=2) and EXCP I/O drivers can handle database files on EAV. The EATTR option is effective only in z/OS version 1.12 and later; in all other environments it is ignored with no error message. Note: Server data sets are not supported when allocated above the 64K cylinder boundary. An attempt to open any server data set allocated above 64K cylinders results in issuing error message M204.2917 (which identifies the server data set name) and run termination.
GDGRECNT	(Only z/OS.) Available as of Model 204 V7.5. Causes Model 204 to check the catalog information for the latest relative GDG generation number whenever allocating a GDG data set. This checking ensures that the data set is allocated with the latest generation number, taking into account GDG data set allocations or deletions by all jobs in the current environment. By default, Model 204 checks the catalog information for the latest relative GDG generation number only when allocating the first GDG data set. The job then determines subsequent GDG generation numbers based only on its own allocations and deletions of the data set. If it deletes the GDG data set, the job might later reuse the same GDG generation number. Examples In the following scenarios, "GDG member" refers to a GDG data set belonging to the same base. Allocations done by one job. If Model 204 defines and allocates a GDG member with GEN=+1, then subsequent attempts to allocate a GDG member with GEN=+1 and without the OLD parameter will result in an error message indicating that the data set has already been allocated. If the GDGRECNT parameter is used in this case, then the next available GDG member will be allocated. Allocations done by multiple jobs. The following is a chronological sequence of events: Model 204 defines and allocates a GDG member with GEN=+1. The allocated member has generation number G0001V00. Model 204 frees the member. Another job or TSO allocates a GDG member with GEN=+1. The allocated member has generation number G0002V00. Another job or TSO deletes the member with generation number G0001V00. Model 204 defines and allocates a GDG member with GEN=+1. Without the GDGRECNT parameter, the allocated member has generation number G0001V00. With the GDGRECNT parameter, the allocated member has generation number G0003V00. Note: GDGRECNT is not allowed with the OLD option.
GEN	(Only z/OS.) Indicates a Generation Data Group (GDG) member.
LABEL	(Only z/OS.) Describes the label associated with a data set. The default is standard labels. Acceptable values that can be specified are as follows: AL – American National Standard label. AUL – American National Standard label and an American National Standard user label. BLP – Label processing should be bypassed. LTM – System is to check for and bypass a leading tape mark on a z/VSE unlabeled tape. NL – No label. NS – Non-standard label. SL – Standard labels. SUL – Both standard and user labels. This option applies only to dynamic allocation of tape data sets, which is valid only under z/OS.
LARGE	(Only z/OS 1.7 and later) Indicates a data set that exceeds 65,535 tracks. May be specified for CCAJRNL, CCAJLOG, including GDG and stream-based journals; large data sets for dumping and/or restoring Model 204 files; and Model 204 file data sets. Can be specified for CHKPOINT data sets in Model 204 version 7.7 and later. SEQUENTIAL and SAM are required coordinating options.
LRECL	Specifies the logical record length (in bytes) for the data set. If the record format is V, LRECL must include the record descriptor word of four bytes. If the record format is A, LRECL must include the one-byte carriage control character. If the records are variable or undefined in length, LRECL must specify the maximum logical record length. The range of acceptable values for the LRECL option is 1 to 32767. This option is used only for non-Model 204 files.
MCLASS	(Only z/OS.) Designates SMS management class allocation.
MEMBER	(Only z/OS.) Indicates PDS format on a new allocation. The NEW parameter is required; if you open a PDS without a MEMBER name, it is treated as a sequential data set.
MEMORY	(Only z/VM and z/OS.) Designates an in-memory file, specifically an above-the-bar memory object. Used with PAGES.
NCP	Indicates the number of channel programs used by BSAM for this data set during output when the Multiple Buffers feature is invoked. The maximum value is 99. The default is one. See the BUFNO option earlier in this table for related information.
NEW or OLD or COND	Indicates whether the data set is created in the current session. The NEW option specifies that the data set is created. It is the default, unless the APPEND option has also been chosen. When the NEW option is specified, the BLOCK/TRACK/CYLINDER, PRIMARY, and, under z/VM, VOLUME options must be specified for dynamic allocation to succeed. The OLD option indicates that the data set specified in the DSNAME option already exists. If the OLD option is not specified, the ALLOCATE or DEFINE command must provide the PRIMARY and VOLUME (z/VM) options. The COND option indicates that the data set specified in the DSNAME option might already exist. COND is the default option if the APPEND option has also been chosen. If the data set does not exist, it is allocated as NEW. (Refer above to the conditions attached to the use of the NEW option.) If the data set does exist, it is allocated as OLD.
PAGES	(Only z/VM and z/OS.) Specifies the number of Model 204 (6K) pages to allocate for an in-memory file. Used with MEMORY.
PASSWORD	Specifies the VSAM access password assigned when the cluster was defined. The password can include any character except those reserved for special functions (such as end-of-line or Model 204 word separator characters). A hexadecimal password is not supported. The password is checked against the VSAM catalog for the data set. It is also checked for each OPEN DATASET statement for the data set. This option is used for non-Model 204 files.
PDS	(Only z/OS.) Indicates PDS format on a new allocation. The NEW parameter is required; if you open a PDS without a MEMBER name, it is treated as a sequential data set.
PDSE	(Only z/OS.) PDS extended format.
POSITION	(Only z/OS.) Specifies the position of the file on the tape. If this option is not specified, POSITION=1 is assumed. Thus this option is required if the data set wanted is not the first data set on the tape. The maximum acceptable value for this option is 9999. For scratch tape data sets, a value greater than 1 is invalid. This option applies only to dynamic allocation of tape data sets which is valid only under z/OS.
PRIMARY	(Only z/OS.) Specifies the amount of space in BLOCKS, TRACKS, or CYLINDERS allocated for a new data set. There is no default. This option applies only to dynamic allocation of new data sets.
RECFM	Specifies the way the physical records are structured.Model 204 recognizes the following five record format attributes: F (fixed), V (variable), U (undefined), B (blocked), and A (printer carriage control). Valid combinations are: FA VA UA FB VB FBA VBA F V U This option applies only to non-Model 204 files.
RELEASE or NORELEASE	Determines whether all unused external storage space assigned to this data set is released at the end of processing. The RELEASE option specifies that the unused storage space is released. Specifying the NORELEASE option retains all the disk storage requested in the PRIMARY parameter when processing is completed. The RELEASE and NORELEASE options apply only to dynamic allocation of new data sets under z/OS.
RETENTION	Specifies the retention period in days, up to 9999 days.
RETRYALLOC	(z/OS and z/VM only.) RETRYALLOC=n is the number of times to retry dynamic allocation failures. The default is zero (which means do not retry). Any value between 0 and 255 is permitted. Model 204 supports the dynamic recall of migrated data sets. When dynamic recall is requested, the user making the request through the USE or OPEN DATASET command enters a wait state until the data set is recalled. However, other users in the Online are not affected. This support is enabled through the RETRYALLOC and RETRYTIME parameters of the DEFINE DATASET command.
RETRYTIME	(z/OS and z/VM only.) RETRYTIME=n defines the time to wait between dynamic allocation retries in seconds. The default is zero (which means to retry immediately). Any value between 0 and 32767 is permitted. Model 204 supports the dynamic recall of migrated data sets. When dynamic recall is requested, the user making the request through the USE or OPEN DATASET command enters a wait state until the data set is recalled. However, other users in the Online are not affected. This support is enabled through the RETRYALLOC and RETRYTIME parameters of the DEFINE DATASET command.
ROUND	Rounds block allocations up to the cylinder boundary on a new allocation.
SCLASS	(Only z/OS.) Designates the SMS storage class allocation.
SECONDARY	Specifies the amount of space that is allocated if the PRIMARY space allocation is exceeded. If necessary, the operating system allocates a maximum of 15 secondary amounts of the type requested (BLOCK, TRACK, or CYLINDER). SECONDARY is optional and has no default value. SECONDARY might be specified under z/VM but no secondary allocation occurs. The secondary space information is stored in the VTOC (Volume Table of Contents) when allocation is done under z/VM. This enables secondary space allocation to be performed under z/OS when the primary space allocation of the data set is filled up. The SECONDARY option is meaningful only when dynamically allocating new data sets.
SEQUENTIAL or KEYED or KEYED SEQUENTIAL or DIRECT or SAM or VSAM or DAM	Indicates the file organization and access method. SEQUENTIAL is the default. The access method specified depends on the file: For SEQUENTIAL files, the access method must be SAM or VSAM. The default is SAM. If VSAM is specified, the file is a VSAM key-sequenced file (KSDS) and access by key is not allowed. For KEYED or KEYED SEQUENTIAL files, the access method must be VSAM. The file can be accessed by key or in sequential order. For DIRECT files, the access method must be DAM. DIRECT means that the file is a Model 204 file.
SHARE or EXCLUSIVE	(Only z/OS.) Determines the type of operating system enqueue to be obtained. For example, a combination of OLD and SHARE allows other jobs to share access to a data set with Model 204. SHARE is the default.
SMSLIKE	(Only z/OS.) Designates the SMS model data set name allocation. Must be used with a =dsn option.
STRINGS	Specifies the number of concurrent access strings (positioning) to a VSAM file. The default value is 1. The STRINGS value can be overridden by the STRNO subparameter of the AMP parameter in the JCL DD statement (only z/OS). This option is used for non-Model 204 files.
TIOT or XTIOT	(Only z/OS.) TIOT specifies that the number of dynamically allocated data sets is limited to 3,273. XTIOT specifies that the number of dynamically allocated data sets is limited by only the amount of processor storage. The XTIOT option requires the OLD and DIRECT options to process without error.
UNIT	(Only z/OS.) Specifies the unit name of the I/O device for the data set. Typical unit names are DISK, TAPE, and SYSDA (the default). The UNIT option is meaningful only during dynamic allocation.
VOLMAX	Specifies the maximum volume count.
VOLSEQ	Specifies the volume sequence number.
VOLUME	Specifies the volume on which a data set resides or on which a new data set is placed. A volume can identify a tape or disk. This option is required under z/VM when a new data set is created or when an existing data set is referenced that resides on an unaccessed OS-format or z/VSE-format minidisk. The VOLUME option is meaningful only during dynamic allocation.

Syntax notes

Any number of DEFINE DATASET options can be specified. Options must be separated by commas or by one or more blanks. A continuation character (-) is required at the end of an input line if the options continue onto the next line.

The DEFINE DATASET command does not check the validity of such options as LRECL, BLKSIZE, and RECFM. They are verified against one another when the data set is opened.

For general syntax and usage notes that apply to all forms of the DEFINE command, see DEFINE command.

Examples

Example 1: New sequential data set

This example defines a new sequential data set with a name of OUTFILE:

DEFINE DATASET OUTFILE WITH SCOPE=SYSTEM - LRECL=80 BLKSIZE=800 RECFM=FB SEQUENTIAL - PRIMARY=150 BLOCK VOLUME=RPG001

Example 2: New data set with a template

This example defines a new data set and gives it all the attributes of the previously defined data set (template):

DEFINE DATASET TEST LIKE OUTFILE WITH SCOPE=SYSTEM

Example 3: Catalogued tape data sets

These examples define catalogued tape data sets:

DEFINE DATASET TAPEFILE WITH SCOPE=SYSTEM - DSNAME=DATA.SET.NAME DEFINE DATASET TAPE2 WITH SCOPE=SYSTEM - DSNAME=DATA.SET.ID LABEL=BLP POSITION=3 - TAPE=UNIT VOLUME=TVOL

Example 4: Uncatalogued tape data sets

This example defines an uncatalogued tape data set:

DEFINE DATASET TAPEFILE WITH SCOPE=SYSTEM - DSNAME=DATA.SET.NAME UNIT=TAPE - VOLUME=TAPVOL

Example 5: SEQUENTIAL file organization, SAM access method

The following example defines a data set with a SEQUENTIAL file organization and an access method of SAM:

DEFINE DATASET XYZ - WITH SCOPE=SYSTEM SEQUENTIAL - SAM BLKSIZE=4080 LRECL=80 - RECFM=FB

Example 6: KEYED file organization

The following example defines a data set with a KEYED file organization, an access method of VSAM, an EOJ parameter for the CLOSE option, and a VSAM password termed ANYTHING:

DEFINE DATASET RPQ - WITH SCOPE=SYSTEM KEYED - VSAM CLOSE=EOJ - PASSWORD=ANYTHING

Example 7: In-memory file (z/OS and z/VM)

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

DEFINE DATASET BUSES WITH SCOPE=SYSTEM MEMORY PAGES=10000 DIRECT

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 DEFINE DATASET command can dynamically define the physical characteristics of data sets used in Model 204 and can refer to previously defined data sets through the LIKE phrase. You also can indicate the attributes, such as the DSNAME and SHARE/EXCLUSIVE options, that the operating system needs to create the data set. Options specified in the DEFINE DATASET command override the defaults provided by Model 204.

The DEFINE DATASET command also provides a facility for identifying non-Model 204 files, such as a VSAM file or a basic sequential file, from SOUL requests.

LARGE data sets

You can define a LARGE (> 64K tracks) data set under only z/OS 1.7 or later. The LARGE argument applies to:

• CCAJRNL, CCAJLOG, including GDG and stream-based journals and jlogs

  Note: LARGE CHKPOINT data sets are supported as of Model 204 version 7.7.

• Data sets used for dumping and/or restoring Model 204 files
• Data sets used for sequential output; the USE command or the SOUL WRITE IMAGE statement
• Model 204 file data sets

Note: When defining a pre-existing, LARGE data set, make sure to use LARGE, SAM, and for Model 204 files, SEQUENTIAL in the DEFINE command:

• For non-Model 204, sequential files:

  DEFINE DATASET OUTFILEA WITH SCOPE=SYSTEM OLD LARGE SAM DSN=OUTFILEA.M204

• For Model 204 database files

  DEFINE DATASET MYM204DB WITH SCOPE=SYSTEM OLD LARGE SAM SEQUENTIAL DSN=MYM204DB.M204

Dynamic allocation at OPEN time

You can open data sets that have been defined through the DEFINE DATASET command but that have not yet been allocated. In this case, the data set is dynamically allocated at OPEN time. This is equivalent to issuing a DEFINE DATASET command for a data set, issuing an ALLOCATE command to allocate it, and then opening it. No messages are displayed when the dynamic allocation is performed; messages are issued only if the allocation fails.

Data sets that have been dynamically allocated during open processing are deallocated when they are closed. This is equivalent to closing the data set and then issuing a FREE command for it.

External file identification

External file I/O support allows READ access to any VSAM KSDS (key-sequenced) cluster either via the primary key, or via the alternate index key through a predefined PATH and an ALTERNATEINDEX cluster in the VSAM catalog. For Model 204 to recognize a VSAM file, a DEFINE DATASET command must be used to identify that file and to specify that the VSAM access method be used for accessing that file. In addition, this command must also provide Model 204 with other information, such as the password (if any), the number of access strings, or the close option of the VSAM file.

If access via an alternate key is desired, a DD statement for the predefined PATH (a DLBL statement for z/VSE systems) must be included in the start-up JCL and a DEFINE DATASET command must be issued for the PATH to indicate that it is a VSAM file. For information on the definition for the ALTERNATEINDEX cluster, refer to Alternate index key processing.

External file I/O support allows READ/WRITE access to any sequential file whose organizational structure is in accordance with the BSAM data set structure in the z/OS operating environment or the SAM file structure in the z/VSE operating environment. For a z/VSE operating system, a DEFINE DATASET command must be provided for each sequential file to be accessed. The command must include parameters for BLKSIZE, LRECL, and RECFM.

For a z/OS operating system, Model 204 can obtain that information either from the DCB parameter of the DD statement or from the disk file label. Therefore, the DEFINE DATASET command for a sequential data set is optional.

The external file I/O support feature can be used to directly load a VSAM KSDS file or a VSAM entry-sequenced (ESDS) file, accessing via an ALTERNATEINDEX cluster and a predefined PATH combination, into any Model 204 file. A DEFINE DATASET command must be provided for each VSAM file (or PATH definition if the alternate index is used). In addition, a DD statement (or DLBL statement) for the file or PATH must be included in the JCL for use with the File Load utility (FLOD).

In-memory file allocation and restoration (z/OS and z/VM)

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 parameter 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 and RESTORE commands can process in-memory files.

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

CREATE FILE filename FROM filenam1,filenam2

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

Dynamic tape allocation (z/OS)

Dynamic tape allocation is an extension to dynamic data set allocation. It is supported only under z/OS. In dynamic tape allocation, SVC 99 is used to interact with the tape management system and to perform the actual allocation.

The options for dynamic tape allocation are LABEL, POSITION, and DENSITY. They are described above in the list of options.

Operator messages and interaction for dynamic tape allocation are the same as in standard tape allocation. The operating system controls the exact form of the interaction.

Processing Partitioned Data Sets (PDS) (z/OS)

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. The PDS can be allocated either outside of Model 204 dynamically or within Model 204. In the DEFINE DATASET command, you must use the keyword MEMBER or MEM.

Syntax

[DSNAME=name] [MEMBER=PDS_name]

Examples

The following examples illustrate the DEFINE DATASET command with PDS and MEMBER parameters.

An example of DEFINE DATASET for a NEW PDS and MEMBER:

DEFINE DATASET OUTPDS WITH SCOPE=SYSTEM DSNAME=M204. - OUTPDS MEMBER=MEM1 LRECL=80 BLKSIZE=800 TRACK - PRIMARY=50 SECONDARY=40 DIRECTORY=5 NEW PDS - UNIT=DISK204

An example of a DEFINE DATASET command for an existing PDS data set and MEMBER. You can write over the MEMBER if it already exists:

DEFINE DATASET OUTPDS WITH SCOPE=SYSTEM - DSNAME=M204.OUTPDS MEMBER=MEM1 OLD

An example of a DEFINE DATASET command for the same PDS as above, but a different MEMBER:

DEFINE DATASET OUTPDS2 WITH SCOPE=SYSTEM - DSNAME=M204.OUTPDS MEMBER=MEM2 OLD UNIT=3380 - VOLUME=OS8U01

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 the following message:

M204.2167: A CLOSE ERROR HAS BEEN DETECTED ON DATASET dddddddd

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 DEFINE DATASET command to have no effect when opening for output a new member of a PDS, as long as no other errors occur.

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 DATASET 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 fails 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, SOUL 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.

PDS members open for input

You can access a PDS simultaneously for multiple input data sets and for one output data set, with all allocations using the OLD and SHARE options of the DEFINE DATASET command.

Processing generation data group (GDG) data sets (z/OS)

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 DEFINE DATASET. The OLD keyword 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.

The syntax on a DEFINE statement for a GDG data set is:

[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 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 new GDG data set

To create a new GDG data set, use the GEN=+1 keyword on DEFINE. The GDG base file must have been built previously using an IDCAMS DEFINE command, 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.)

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.

z/VSE considerations

The DEFINE DATASET command allows the z/VSE user to:

• Translate a Model 204 internal 8-character file name into a 7-character z/VSE file name acceptable for use on a DLBL or TLBL statement.
• Relate a Model 204 data set name to a logical unit number. This is especially helpful when the data set is being routed to a file that cannot be referenced by a data set name such as a tape file.
• Route output from a USE command to a printer, punch, or tape device. (Refer to the discussion in this section on the USE command and directing output to a sequential data set.) The DEFINE DATASET command is required in this case, because USE output files must be routed to data set names that begin with the characters OUT.
• Indicate options (RECFM, LRECL, BLKSIZE) that cannot be specified in z/VSE JCL.

The following example relates the internal Model 204 filename, ADDRFILE, to the 7-character z/VSE filename, ADDRFIL:

DEFINE DATASET ADDRFILE WITH SCOPE=SYSTEM FILENAME=ADDRFIL

This z/VSE example describes a USE file whose output is directed to a printer with a logical unit name of SYS001:

// ASSGN SYS001,02E . . . DEFINE DATASET OUTFILE WITH SCOPE=SYSTEM FILENAME=SYS001 LRECL=121 USE OUTFILE

Positioning before User 0's parameter line

The DEFINE DATASET command can precede User 0's parameter line in the CCAIN input stream. It is required when you use either of the following:

• RESTART facility for recovery of a Model 204 file in which the internal file name has been related to an 8-character z/VSE file name. Examples of this type of file are the Dictionary files METADATA, DATAPROC, and DATALINK.
• Tape journals or checkpoint data sets for RESTART recovery. The z/VSE example below shows a sample Job Control stream that can be used when the data sets CCAJRNL and CHKPOINT are on magnetic tape:

  // JOB MODEL204 . . . // TLBL SYS040,'M204.CHKPOINT',99/365 // ASSGN SYS040,TAPE // TLBL SYS041,'M204.JOURNAL',99/365 // ASSGN SYS041,TAPE . . . // EXEC ONLINE,SIZE=AUTO . . . DEFINE DATASET CHKPOINT WITH SCOPE=SYSTEM - FILENAME=SYS040 DEFINE DATASET CCAJRNL WITH SCOPE=SYSTEM - FILENAME=SYS041 PAGESZ=6184,RCVOPT=9,...

Refer to the discussion on recovery file specification in Recovery data sets and job control for a detailed explanation of this feature.

z/VSE/POWER identification

Under z/VSE/POWER, the implementation of directed output uses a DEFINE DATASET CCAPPRn/CCAPPUn command to specify a logical unit name (SYSxxx) that appears in a JCL ASSGN statement defining a POWER printer or punch device.

Printer and punch devices for z/VSE/POWER are identified in the following manner:

DEFINE DATASET powername WITH SCOPE=SYSTEM,DDNAME=SYSxxx

where powername is CCAPPR, CCAPPR1, . . . for POWER printer devices and CCAPPU, CCAPPU1, . . . for POWER punch devices. For more information, refer to Using z/VSE/POWER.

Reading records from a sequential or VSAM file

Under z/VSE, whenever you read records from a sequential or VSAM file into an image, you must provide a DEFINE DATASET command for the source file that specifies values for at least RECFM and DATALEN. These values must be the same as those in effect when the sequential file was created. If you do not provide a DEFINE DATASET command when you attempt to read the file, you receive an I/O error.

The simplest DEFINE DATASET command you can use when reading a sequential file into an image under z/VSE is:

DEFINE DATASET filename WITH SCOPE=SYSTEM RECFM=aa DATALEN=nnn

Where:

• filename is the name of the sequential data set containing the data you want to read.
• aa is the record format of the sequential file.
• nnn is the record length of the sequential file.

The values of RECFM and DATALEN default to the values of the parameters UDDRFM (VA unless reset) and OUTMRL (132 unless reset). Thus, if all defaults are in effect at the time the sequential file is created, the DEFINE DATASET command takes the form:

DEFINE DATASET filename WITH SCOPE=SYSTEM RECFM=VA DATALEN=132