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. File Manager may also issue the 999 abend, if the return code in batch is equal to or greater than the ABENDCC value. Contact your File Manager systems administrator for details.

Related functions

BT: Write test data to a tape file
INT: Initialize a tape

Figure 1. Syntax

Template processing options

Copybook processing

COBOL options

PL/I options

HLASM options

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, File Manager displays a list of matching managers to select from.
queuename: The queue to be used. If you specify a generic name, File Manager 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 File Manager 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 File Manager 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, File Manager 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 File Manager 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.

File Manager 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 File Manager 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 File Manager to write the output in ISPF packed format.
NONE: Instructs File Manager 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 File Manager 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), File Manager uses these processing options to compile the copybook into a template:

LANG

Determines whether File Manager 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, PL/I, or Assembler and invoke the appropriate compiler. If the compilation results in a return code greater than the maximum allowed return code for that language, and no template can be produced, then the compilation error is reported. If File Manager successfully creates a template (despite the compilation errors), then it continues 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.

DSINFO

Specifies whether additional data set information for input and output sources should be produced in batch reports for the DSP, DSM, DSC, and FCH commands.

NO: No additional data set information is generated.
YES: Generates data set information including DSORG, RECFM, LRECL, BLKSIZE, and VSAM attributes including average record length, maximum record length, key offset, key length and reuse, for input and output data sets when applicable.

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

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

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
//*
//FMBAT    PROC
//FMBAT    EXEC PGM=FILEMGR
//STEPLIB  DD DSN=FMN.SFMNMOD1,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 FMNUSER.VSAM.DSG25 CLUSTER PURGE ERASE
 DEFINE CLUSTER ( -
      NAME( FMNUSER.VSAM.DSG25 ) -
      CISZ(4096) -
      FREESPACE(30 30) -
      NONINDEXED -
      KEYS(12 0) -
      RECORDS(1000 100) -
      RECORDSIZE(234 234) -
      REUSE) -
      DATA( NAME(FMNUSER.VSAM.DSG25.DATA) )
/*
//*
//STP1005     EXEC FMBAT
//DDOUT  DD DISP=SHR,DSN=FMNUSER.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 FMBAT
$$FILEM DSG DSNOUT=TEST.BASE.NEW,
$$FILEM LIKE='FMN.TEST.BASE.RFM0041.SEGMENT.PS',
$$FILEM DISP=MOD,
$$FILEM PACK=NONE,
$$FILEM NLRECS=100
/*