DSG (Data Set Generate)

Purpose
Use the DSG function to create and initialize data values in VSAM data sets, sequential data sets, PDS members, HFS files, MQ queues, or CICS® resources.

You specify the number of records that are to be created and how they are to be initialized. You can initialize the data with fill characters and patterns. When you use a copybook or a template you can initialize records at the field level. You can change the field create attributes for individual fields by editing the copybook or template.

Options
You can specify a fill character or fill pattern, a sequence field, and a block size.
Return codes
The default return codes from the DSG function have the following modified meanings:
4
No records generated because zero records specified
16
No records generated because DISP=MOD specified for member
16
No records generated because key not fully within data
16
Member name required and not specified
16
Program Object specified - this is not supported
16
Data set in use
16
Data set or member in use
16
Data set or member open error
16
Other input or output error occurred
16
Insufficient storage available
16
DSG abended
16
Other serious error that stops processing occurred
Note: Return codes can be customized during installation. If you receive return codes that do not match those listed above, your site might have customized the return codes for this function. Z Data Tools may also issue the 999 abend, if the return code in batch is equal to or greater than the ABENDCC value. Contact your Z Data Tools systems administrator for details.
Related functions
BT
Write test data to a tape file
INT
Initialize a tape
Read syntax diagramSkip visual syntax diagram
Syntax

>>-DSG---------------------------------------------------------->

     .-OUTPUT=DDOUT-------------------------------------------.     
>----+--------------------------------------------------------+---->
     +-OUTPUT=ddname------------------------------------------+     
     '-DSNOUT=-+-dsname--+----------+--+------------------+-+-'     
               |         '-(member)-'  '-VOLSEROUT=volser-' |       
               +-MQ:manager:queuename-----------------------+       
               '-rt:applid:rname----------------------------'       

   .-USEIOXOUT=NO---------------------.   
>--+----------------------------------+------------------------->
   |               .-IOXOUT=sysexit-. |   
   '-USEIOXOUT=YES-+----------------+-'   
                   '-IOXOUT=ioxname-'     

                                .-REUSE=NO--.  .-DISP=MOD-.   
>--+-------------------------+--+-----------+--+----------+----->
   '-BINRECOUT=binrecout-len-'  '-REUSE=YES-'  '-DISP=OLD-'   

>--+-----------------+--NLRECS=nlrecs--+-------------------+---->
   '-RECSIZE=recsize-'                 '-FILLCHAR=fillchar-'   

>--+-----------------------------------------------+------------>
   |               .-KEYLEN=8------. .-INCR=10---. |   
   '-KEYLOC=keyloc-+---------------+-+-----------+-'   
                   '-KEYLEN=keylen-' '-INCR=incr-'     

                     .-PACK=NONE-.   
>--+--------------+--+-----------+------------------------------>
   '-LIKE=likedsn-'  '-PACK=PACK-'   

>--+---------------------------------+-------------------------><
   '-| Template processing options |-'   

Template processing options

   .-TOUTPUT=TDDOUT--------------------.   
|--+-----------------------------------+------------------------>
   +-TOUTPUT=ddname-+----------------+-+   
   |                '-TOUTMEM=member-' |   
   '-TCOUT=tcout(member)---------------'   

>--+------------------------------------------------------+----->
   '-OFFSETOUT=(-+-value-+------+---------------------+-)-'   
                 |       '-,ALL-'                     |       
                 |                .-,---------------. |       
                 |                V                 | |       
                 '-+------------+---value,fieldname-+-'       
                   '-value,ALL,-'                             

>--+---------------------------------+--------------------------|
   '-| Copybook processing options |-'   

Copybook processing options

   .-LANG=AUTO-------.                                        
|--+-----------------+--| COBOL options |--| PL/I options |----->
   '-LANG=-+-COBOL-+-'                                        
           +-PLI---+                                          
           '-HLASM-'                                          

>--| HLASM options |--------------------------------------------|

COBOL options

   .-DBCS=NO--.  .-CDPC=NO--.  .-CAE=NO--.  .-MIXED=NO--.   
|--+----------+--+----------+--+---------+--+-----------+------->
   '-DBCS=YES-'  '-CDPC=YES-'  '-CAE=YES-'  '-MIXED=YES-'   

>--+----------------------------------------+------------------->
   | .------------------------------------. |   
   | V                                (1) | |   
   '---RFROMn=operand1--RTOn=operand2-----+-'   

>--+------------------+-----------------------------------------|
   '-CBLADDOP=options-'   

PL/I options

   .-BIN63=NO--.  .-DEC31=NO--.  .-GRAPHIC=NO--.   
|--+-----------+--+-----------+--+-------------+---------------->
   '-BIN63=YES-'  '-DEC31=YES-'  '-GRAPHIC=YES-'   

   .-UNALIGNED=NO--.  .-PLIMAXRC=4---.   
>--+---------------+--+--------------+-------------------------->
   '-UNALIGNED=YES-'  '-PLIMAXRC=num-'   

>--+------------------------+--+------------------+-------------|
   |           .--------.   |  '-PLIADDOP=options-'   
   |           V        |   |                         
   '-PLILIBS=(---dsname-+-)-'                         

HLASM options

   .-DBCS=NO--.  .-NOALIGN=NO--.  .-ASMMAXRC=4---.   
|--+----------+--+-------------+--+--------------+-------------->
   '-DBCS=YES-'  '-NOALIGN=YES-'  '-ASMMAXRC=num-'   

>--+------------------------+--+------------------+-------------|
   |           .--------.   |  '-ASMADDOP=options-'   
   |           V        |   |                         
   '-ASMLIBS=(---dsname-+-)-'                         

Notes:
  1. n= 1 to 5.
OUTPUT=ddname
Defines a reference to a DD or TSO ALLOC statement for the output data set or HFS file. The default is DDOUT.
DSNOUT=dsname
Defines the name of the output data set or an absolute path to the output HFS file. If any DD statements are specified, they are not used. The name may include a member name in parenthesis. If the member is specified here, the associated Member parameter must be empty.

An absolute path to an HFS file (directory) must be enclosed in apostrophes. If it does not fit on one line, you can split it overmore than one line.

You can further describe this data set, as follows:
(member)
Where DSNOUT=dsname specifies a PDS and you want to send the output to a specific member within this data set, this defines the output member name.
VOLSEROUT=volser
Volume serial number for a new or non-cataloged data set.
MQ:manager:queuename
You can specify a MQ queue in place of a data set name, where:
manager
The MQ manager to be used. If you specify a generic name, Z Data Tools displays a list of matching managers to select from.
queuename
The queue to be used. If you specify a generic name, Z Data Tools displays a list of matching queues to select from.
rt:applid:rname
You can specify a CICS resource in place of a data set name, where:
rt
Resource type. Valid values are:
FI
For a CICS file.
TD
For a Transient Data Queue.
TS
For a Temporary Storage Queue.
applid
The VTAM® applid of the CICS system.
rname
The name of the resource.
USEIOXOUT
Specifies whether to invoke a user I/O exit, to process the output data set.
NO
Default. Do not invoke a user I/O exit.
YES
Invoke a user I/O exit to process the output data set. This option is only available if the person who did the site customization for Z Data Tools allowed user I/O exits on a site-wide basis.
IOXOUT
Specifies the name of the user I/O exit used for the output data set. There are no restrictions on the programming language that you can use to write an exit. The exit must be provided to Z Data Tools in the STEPLIB/ISPLLIB concatenation or their extensions (LINKLIST, LPA, and so on).
sysexit
Default. If you specify USEIOXOUT=YES and do not supply a user I/O exit name, Z Data Tools uses the name of the exit provided in the installation customization options. If USEIOXOUT has been set to YES and no installation default has been provided, you must specify IOXOUT=ioxname.
Note: If you have selected batch processing in an online panel, the generated JCL statements use the default name provided in your Set System Processing Options panel.
ioxname
The name of a PDS(E) member of a data set that has been provided to Z Data Tools in the STEPLIB concatenation.
BINRECOUT=binrecout-len
Specifies the record length for processing the HFS file. Valid range: 1 to 32760.

The file is processed in Binary mode (fixed-length records derived from the file, delimiters not distinguished). If you do not specify this parameter, the file is processed in Text mode (variable-length records, boundaries determined by delimiters).

REUSE
Specify YES to replace any existing records in the output data set (if it is defined with the REUSE parameter in the catalog). Specify NO to add new records without deleting the old records. The default is NO.
DISP
Disposition of the output data set. Specify OLD or MOD.
OLD
Writes input records to the existing output data set, starting from the beginning.
MOD
Default. Appends the input records to the end of the existing output data set.
Note: If you are appending to a sequential data set, ensure that the existing data set does not contain data in ISPF Packed Data format. Appending records to a packed data set results in data errors.
Note: SMS might modify the allocation of new data sets on your system. For details, contact your SMS Administrator.
RECSIZE=recsize
1-9999999, depending on the output file characteristics.

For fixed record formats the record length is set to the record length and user input is ignored.

For undefined record formats the record length is set to the block length and user input is ignored.

For variable record formats the record length specified is used if it is less than the maximum record size. Otherwise the maximum record size is used and user input is ignored.

When the data create function is used with a template, the length of the records written depends upon whether the records are fixed-length or variable-length, and the length of the record description in the template (note that the length of the record in the template must always be less than or equal to the data set record length). The value specified in recsize is ignored when using a template.

For fixed-length records created with a template, all records have the length specified for the data set. If the length of the record in the template is less than the data set record length, the records are padded with the fill character.

For variable-length records created with a template, the length of each record depends on the length of the record built using the field attributes in the template. If the template record description contains one or more variable-length arrays, the length of the record varies according to the value or values assigned to objects of the OCCURS DEPENDING ON clauses.

NLRECS=nlrecs
Number of logical records to be written. The maximum is 999 999 999.
FILLCHAR=fillchar
To fill each byte of each record with data, specify one of the following:
char
A character, such as 0 to be written in each byte. (To specify a lowercase character such as 'a', use either C'a' or X'81'.)
X'cc'
A binary character, such as X'04' to be written in each byte.
AN
To write alphanumeric characters (A to Z and 0 to 9).
BIN
To write binary characters (X'00' to X'FF').
RAND
To write random binary characters (X'00' to X'FF').

If you specify AN or BIN, characters are written in a “ripple” pattern. For example, if you specify AN, the first 3 records look like this:

  ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789A
  BCDEFGHIJKLMNOPQRSTUVWXYZ0123456789AB
  CDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABC

The default is a blank.

KEYLOC=keyloc
Position (starting with 1) of the sequence field within the output records. If omitted, there is no sequence field.
Note: KEYLOC is not the same as a VSAM KSDS key position. KEYLOC refers to a "virtual" key field (sequence number) created in all records to identify a specific record within a file.
KEYLEN=keylen
Length of the sequence field, from 1 to 9. The default is 8.
Note: KEYLEN is not the same as a VSAM KSDS key length. KEYLEN refers to a "virtual" key field (sequence number) created in all records to identify a specific record within a file.
INCR=incr
Increment value for the sequence field. The default is 10.
LIKE=likedsname
Name of the data set to be used as the model for the output allocation.

Z Data Tools uses the TSO prefix (as defined for your user ID) used as the high-level qualifier for any name that is not enclosed in quotation marks.

If copying data sets, "=" denotes the current input data set.

The model data set must reside on a DASD volume, be cataloged, and SMS must be active.

PACK
Determines if Z Data Tools writes the output data in ISPF packed format. This keyword is ignored when processing VSAM data sets. When an I/O exit has been specified for either the input or output data set (or both), the only valid option is PACK=NONE.
PACK
Instructs Z Data Tools to write the output in ISPF packed format.
NONE
Instructs Z Data Tools not to write the output in ISPF packed format.
Note: Do not use the DISP=MOD and PACK=PACK option at the same time. Appending packed data to a packed or non-packed sequential data set results in data errors. Appending non-packed data to a packed data set also results in data errors.
Template processing
The template processing parameters define which template is used to describe the structure of the new records and how Z Data Tools processes the template.
TOUTPUT=ddname
Defines a reference to a DD or TSO ALLOC statement for the data sets which contain the copybook or template that describes the record structure of your output data. The default is TDDOUT.

If you specify a concatenated DD, then you must provide the member name, member.

TOUTMEM=member
The name of the copybook or template member in the datasets identified by the TOUTPUT parameter if it has not been specified on the DD statement. This parameter must not be specified if the TCOUT parameter is specified.
TCOUT=tcout(member)
PDS and member name of the copybook or template that describes the record structure of your output data.
OFFSETOUT
The length of the 01 field in the template and the start locations of the fields within that 01 field are adjusted by the value provided.
value
The offset value, which must be in the range -32760 to 32760, to be applied to the corresponding field identifier. If no field identifier is supplied and ALL is not used, the value is applied to the first Level 01 field in the “To” template.
ALL
Where the template contains multiple record structures, this keyword applies the corresponding value to all Level 01 fields within the “To” template.
Note: You can specify a value for ALL and then override this value for individual layouts by providing subsequent value and fieldname combinations.
fieldname
The name of the Level 01 field to which value is applied. The default is the first Level 01 field in the “To” template.
Copybook processing
If you specify a copybook (instead of an existing template), then Z Data Tools uses these processing options to compile the copybook into a template:
LANG
Determines whether Z Data Tools automatically detects the copybook language or interprets the language as COBOL, PL/I, or HLASM.
Note: The COMPLANG setting in FMN0POPT is the equivalent of the LANG parameter in batch functions.
  • If COMPLANG is set it determines the installation default language for online and batch compilation.
  • If COMPLANG is not specified then COBOL is the installation default for online compilation and AUTO is the default for batch compilation.
  • If a value of COBOL, HLASM, PL/1, or AUTO is specified (in the Compiler Language Selection panel or through the LANG parameter in a batch job) it overrides the default language.
AUTO
Automatically detect whether the copybook language is COBOL or PL/I, and invoke the appropriate compiler. If the compilation results in a return code greater than 4, then invoke the compiler for the other language. If the second compilation also results in a return code greater than 4, then retry the first compiler and report the compilation errors. If Z Data Tools successfully creates a template (despite the compilation errors), then continue processing with the template.
COBOL
Invoke the COBOL compiler to create a template from the copybook. (Do not invoke the PL/I compiler, even if the COBOL compilation results in errors.)
PLI
Invoke the PL/I compiler to create a template from the copybook. (Do not invoke the COBOL compiler, even if the PL/I compilation results in errors.)
HLASM
Invoke the HLASM compiler to create a template from the copybook.
COBOL options
The following options are used to compile a COBOL copybook into a template:
DBCS=YES
Use the DBCS compiler option.
DBCS=NO
Use the NODBCS compiler option.

For details on the effect of the DBCS and NODBCS compiler options, see the IBM COBOL Programming Guide for OS/390 & VM.

CDPC=NO
Do not use the COBOL SPECIAL-NAMES paragraph "Decimal-point is comma".
CDPC = YES
Use the COBOL SPECIAL-NAMES paragraph "Decimal-point is comma".
CAE=NO
Do not use the COBOL compile option ARITH(EXTEND).
CAE = YES
Use the COBOL compile option ARITH(EXTEND).
MIXED = NO
Field names stored in the template in uppercase.
MIXED = YES
Field names stored in the template in the original case as coded in the COBOL copybook.
RFROM1 RTO1 … RFROM5 RTO5
Up to five pairs of “From” and “To” pseudo-text character strings for the COBOL REPLACE compiler-directing statement.

If your COBOL copybooks contain characters that you want to remove or replace with other characters before compiling the copybooks into templates, then use these replacing options.

For example, if your copybooks contain colon characters (:) that you want to remove before compiling, then specify '==:==' as operand1 and '=====' as operand2.

For details on specifying “From” and “To” strings for COBOL REPLACE, see the IBM COBOL Language Reference.

CBLMAXRC
Sets the maximum acceptable return code for a copybook compile. A return code higher than the specified level causes the function to stop. Default is 4.
Note: The COMPMAXRC parameter is still supported but it is recommended that the CBLMAXRC parameter is used instead. If you do specify the COMPMAXRC parameter, it takes precedence over the language MAXRC.
CBLLIBS
Allows you to specify a list of up to ten data set names to be specified in the SYSLIB concatenation list. These data sets are searched in the order specified for COPY and INCLUDE members for the compilation.
dsname
The name of the data set name to be processed. Generic name masks are not allowed.
CBLADDOP
Additional COBOL compiler options which are included in a CBL statement when compiling COBOL copybooks.
PL/I options
The following options are used to compile a PL/I copybook into a template:
BIN63=YES
Use the LIMITS(FIXEDBIN(63)) compiler option.
BIN63=NO
Use the LIMITS(FIXEDBIN(31)) compiler option.
DEC31=YES
Use the LIMITS(FIXEDDEC(31)) compiler option.
DEC31=NO
Use the LIMITS(FIXEDDEC(15)) compiler option.
GRAPHIC=YES
Use the GRAPHIC compiler option.
GRAPHIC=NO
Use the NOGRAPHIC compiler option.
UNALIGNED=YES
Use the DEFAULT RANGE (*) UNALIGNED, language statement to change the default alignment.
UNALIGNED=NO
Use the PL/I default.
PLIMAXRC
Sets the maximum acceptable return code for a copybook compile. A return code higher than the specified level causes the function to stop. Default is 4.
Note: The COMPMAXRC parameter is still supported but it is recommended that the PLIMAXRC parameter is used instead. If you do specify the COMPMAXRC parameter, it takes precedence over the language MAXRC.
PLILIBS
Allows you to specify a list of up to ten data set names to be specified in the SYSLIB concatenation list. These data sets are searched in the order specified for COPY and INCLUDE members for the compilation.
dsname
The name of the data set name to be processed. Generic name masks are not allowed.
PLIADDOP
Additional PL/I compiler options which are included in a *PROCESS statement when compiling PL/I copybooks.

For details on the effect of these compiler options, see the IBM VisualAge PL/I for OS/390 Programming Guide.

HLASM options
The following options are used to compile a HLASM copybook into a template:
DBCS=YES
Use the DBCS compiler option.
DBCS=NO
Use the NODBCS compiler option.
NOALIGN=YES
Use the NOALIGN compiler option.
NOALIGN=NO
Use the ALIGN compiler option.
ASMMAXRC
Sets the maximum acceptable return code for a copybook compile. A return code higher than the specified level causes the function to stop. Default is 4.
Note: The COMPMAXRC parameter is still supported but it is recommended that the ASMMAXRC parameter is used instead. If you do specify the COMPMAXRC parameter, it takes precedence over the language MAXRC.
ASMLIBS
Allows you to specify a list of up to ten data set names to be specified in the SYSLIB concatenation list. These data sets are searched in the order specified for COPY and INCLUDE members for the compilation.
dsname
The name of the data set name to be processed. Generic name masks are not allowed.
ASMADDOP
Additional HLASM compiler options which are included in a *PROCESS statement when compiling COPY and MACRO members.
//DSG  JOB (acct),'name'  Create VSAM Data
//*
//HFMBAT    PROC
//HFMBAT    EXEC PGM=HFMMAIN
//STEPLIB  DD DSN=HFM.SHFMMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//         PEND
//*
//IDCPROC  PROC
//IDCAMS   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//         PEND
//*
//*  EXAMPLE DSG JOB
//*  17 RECORDS ARE WRITTEN TO A NONINDEXED
//*  VSAM FILE.  THE OUTPUT FILE CONTAINS
//*  ALPHANUMERIC CHARACTERS.
//*
//DMBBV02   EXEC IDCPROC,REGION=6M
//SYSIN    DD *
 DELETE HFMUSER.VSAM.DSG25 CLUSTER PURGE ERASE
 DEFINE CLUSTER ( -
      NAME( HFMUSER.VSAM.DSG25 ) -
      CISZ(4096) -
      FREESPACE(30 30) -
      NONINDEXED -
      KEYS(12 0) -
      RECORDS(1000 100) -
      RECORDSIZE(234 234) -
      REUSE) -
      DATA( NAME(HFMUSER.VSAM.DSG25.DATA) )
/*
//*
//STP1005     EXEC HFMBAT
//DDOUT  DD DISP=SHR,DSN=HFMUSER.VSAM.DSG25
//SYSIN    DD *
$$FILEM VER
$$FILEM DSG OUTPUT=DDOUT,REUSE=NO,NLRECS=17,
$$FILEM     RECSIZE=234,FILLCHAR=AN
$$FILEM EOJ
/*

This example shows how to define a new data set set using a "model" data set (supports VSAM and non-VSAM data sets) and fill it with some data.

Note that the new data set is allocated based on the "model" data set as described by the LIKE parameter.

 //STP1006 EXEC HFMBAT
$$FILEM DSG DSNOUT=TEST.BASE.NEW,
$$FILEM LIKE='HFM.TEST.BASE.RFM0041.SEGMENT.PS',
$$FILEM DISP=MOD,
$$FILEM PACK=NONE,
$$FILEM NLRECS=100
/*