DSC (Data Set Copy)
- Purpose
- Use the DSC function to copy data from any supported data set to any other supported data set. The function's performance when copying PDS and PDSE data sets greatly depends on the available storage: larger regions generally result in better performance.
- Usage notes
-
- You can select the records to be copied using:
- Member name selection criteria
- Date created selection criteria
- Date last modified selection criteria
- User ID selection criteria
- The start key (VSAM only)
- The skip field
- The copy count field
- A conditional expression defined in the from template
- Change data set attributes. File Manager can copy records where the input and output data sets have different record formats, record lengths, or block sizes. The copy process truncates or pads records appropriately. Specify the pad character in the PAD field of the SET function. For details see SET (Set Processing Options).
- Copy from field to field. Using both a “From” and a “To” template lets you copy selected fields, change the size and type of fields, and create new fields in the output data set. For details, see Copying data sets.
- Copy the output using an external format such as XML or CSV. The "From" template defines the traditional format of a data set, but also determines a natural character representation of the data. The result of the generation is an output data set containing a copy of the input data in the external format. For details, see Generating data in external format - XML representation.
- Copy concatenated data sets with like or unlike attributes. Note that, under some conditions (with tape data sets), File Manager may not be able to detect unlike data set attributes and still invoke DFSORT for processing. Such invocation may fail as DFSORT does not allow for unlike concatenation of data sets. In such cases, you can disable the DFSORT with the NOSORT function to allow for successful processing of concatenated data sets with unlike attributes.
- Change ISPF packed format. File Manager can unpack existing packed members or sequential data sets, or can write members or sequential data sets in ISPF packed format.
- These changes are visible in the printed DSC BATCH processing
report:
- Member names are printed as specified on the CPYMBR list (when used).
- Whenever a member name, its alias or new name (prompt value) contains unprintable characters, an additional line of output is printed below the regular output containing the hexadecimal values of the respective member names.
- Whenever a member was located in the input library and appeared on the CPYMBR list but was not selected for processing because of the member mask or advanced member selection criteria, then it is shown in the processing report as "Not selected" (as opposed to "Not found") and be counted in the "not copied" category (as opposed to "in error").
- For example, with these control cards:
One would see this output:$$FILEM MEMBER=X'5C22', $$FILEM CPYMBR=(C'allocplx', $$FILEM x'8289879784a222', $$FILEM autotest, $$FILEM X'84A282')Member Copy Report Member Newname Alias Status --------------------------------------------------------------------- allocplx Not selected bigpds Replaced X'8289879784A222' AUTOTEST Not found dsb Not selected FMN4688I 0 member(s) copied; 1 replaced; 2 not copied; 1 in error
- Member names containing lowercase or unprintable characters:
- Member names specified with the CPYMBR, MEMBER, MEMSTART, MEMEND, or MEMOUT keywords may contain lowercase or unprintable characters.
- To specify a member name containing lowercase or mixed case characters, use the character
literal form of the name surrounded by quotation marks and preceded with character C. For example,
C'aBc'. - To specify a member name containing unprintable characters, use the hexadecimal literal form of the name surrounded by quotation marks and preceded with character X. For example, X'81C283'. Mask characters (their hexadecimal value) may be included within the string.
Note: File Manager supports the copying of Load Modules, when the following conditions are met:- Your input and output data sets are PDS or PDSE.
- Your TSO environment is active (and you can use the TSO authorized program services), or you are running File Manager as program-authorized.
- You have not specified a REXX user procedure.
- You have not specified Start key, Skip or Copy counts.
- You are not using templates.
- You do not request member record counts.
- You can select the records to be copied using:
- Performance tips
-
- See General tips about performance when you use File Manager functions. The comments about File Manager using DFSORT technology when performing sequential file I/O are important to DSC performance.
- When you are using DSC to copy members of a PDS(E):
- One DSC default is STATS=ON, which causes the ISPF statistics for each copied member to be updated. This can significantly increase I/O (EXCP) and CPU utilization. To improve performance, consider using STATS=OFF.
- File Manager attempts to use IEBCOPY or an equivalent product
to copy members if it can. File Manager using IEBCOPY can significantly
reduce I/O and CPU requirements, compared to File Manager not using
IEBCOPY. If any File Manager processing of individual records is required,
it cannot use IEBCOPY. For example, File Manager cannot use IEBCOPY
if:
- A proc (PROC=) is used.
- A template or copybook is used.
- Record counts are requested (RECCOUNTS=YES).
- File Manager does not use IEBCOPY when processing members of a PDS(E) when it detects any member names containing unprintable or lowercase characters since IEBCOPY is not capable of processing such member names. This may negatively affect the performance of the DSC operation.
- Options
- When you specify the PROC option, you are supplying a DFSORT™ or REXX procedure that controls the selection and formatting used during the copy function. For more information, see the proc parameter below.
- Return codes
- The default return codes from the DSC function have the following
modified meanings:
- 1
- No records copied for some of multiple members.
- 2
- No records copied for any of multiple members.
- 2
- No Copy - duplicate records not copied.
- 2
- No Copy - REXX procedure has dropped records which are not subsequently copied.
- 3
- REXX member selection is in effect but the procedure encountered
a RETURN DROP, STOP or STOP IMMEDIATE string. This has been treated
as a RETURN string with no arguments.
OR
REXX member selection is NOT in effect but the procedure encountered a RETURN DROP MEMBER, RETURN PROCESS MEMBER string. This has been treated as a RETURN string with no arguments.
- 4
- No records copied because no records selected (for single member or data set)
- 4
- No records copied because no members to process
- 4
- No records copied because input empty
- 4
- No records copied because member exists and “no replace” option specified
- 4
- Input data set or member was skipped because it is in ISPF Packed Data format and the “PACK=SKIP” option was specified
- 8
- REXX non-syntax error encountered while processing records
- 8
- Line generated in an external format is greater than output record size.
- 16
- No records copied because input and output physically the same (not applicable to a PDS member)
- 16
- Program Object specified - this is not supported
- 16
- Output data set or member in use
- 16
- Data set or member open error
- 16
- Data set or member not found
- 16
- Other input or output error occurred
- 16
- Insufficient storage available
- 16
- DSC abended
- 16
- Input data appears ISPF packed but is not valid.
- 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
-
- OS
- Backup objects from an OAM database to a data set
- OV
- Backup objects from an OAM database to a VSAM data set
- TS
- Copy tape data to a data set
- SO
- Copy a data set to an object database
- ST
- Copy a data set to tape
- VO
- Copy VSAM data to an object database
Notes:
- 1 VSAM only.
Template options
Input template options
Output template options
Copybook processing
COBOL options
PL/I options
HLASM options
XML export options
CSV export options
- INPUT=ddname
- Defines a reference to a DD or TSO ALLOC statement for the “From”
data set or HFS file. The default is
DDIN. - DSNIN=dsname
- Defines the name of the “From” data set or an absolute
path to the
From
HFS file (directory). If any DD statements are specified, they are not used. The name can 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 over more than one line. You can further describe this data set, as follows:- VOLSERIN=volser
- Volume serial number for a non-cataloged “From” 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.
- MEMBER=member1
- The name of a single member in a PDS, or a member name pattern
representing one or more members in a PDS. If the input data set is
a PDS(E), you may specify this parameter, or a member name in the
DD statement for ddname, or specify a member
or members in the CPYMBR parameter, or specify a range of member names
via the MEMSTART and/or MEMEND keywords.
A member name pattern can consist of any characters that are valid in a member name and two special pattern characters: the asterisk (*) and the percent symbol (%).
- *
- represents any number of characters. As many asterisks as required
can appear anywhere in a member name pattern. For example, if you
enter a member name pattern of
*d*, all members in the PDS whose name contains “d” are processed. - %
- is a place holding character that means a single character. As
many percent symbols as necessary can appear anywhere in a member
name pattern. For example, if you enter a member name pattern of
%%%%, all members in the PDS whose name is four characters in length are processed.
member1 is ignored if the data set is not a PDS.
Note: See Usage notes. - MEMSTART=startstring
- Is used to specify the start of a range of member names to be
included in the copy. If MEMSTART is specified but MEMEND is omitted,
all members of the PDS(E) from the startstring value
onwards are included. startstring can have
the same values, including wild cards, as for the member1 parameter
of the MEMBER keyword. Note: See Usage notes.
- MEMEND=endstring
- Is used to specify the end of a range of member names to be included
in the copy. If MEMEND is specified but MEMSTART is omitted, all members
of the PDS(E) up to the endstring value
onwards are included. endstring can have
the same values, including wild cards, as for the member1 parameter
of the MEMBER keyword. Note: See Usage notes.
- XMEMBERS
- Provides a way to exclude from processing library members that would otherwise be selected using
the MEMSTART, MEMEND, and MEMBER options.
- xmem_filter
- A member name filter identifying one or more members that are to be excluded from processing. A
filter can be a member name pattern representing multiple members.
To specify a member name filter containing lowercase characters, use a character string in the format
c'string'. Filter values can also be specified as hexadecimal strings in the formatx'hex-digits'.
- GEN=generation
- Specifies the generation of the member to be copied. A value of 0 refers to the current member.
A negative value refers to the relative generation number. A positive value refers the absolute
generation number.
If the input data set is not a PDSE that supports member generations, the GEN keyword is ignored.
- MGENS
- Specifies if member generations are to be copied when copying the current member of a PDSE that
supports member generations.
- NO
- Do not copy member generations.
- YES
- Also copy member generations.
- LIMIT=nnnnn
- Specify a limit for the number of generations that will be copied for any given member when MGENS=YES. The default is to copy all generations up to the MAXGENS limit on the output PDSE.
- CREATED=created
- The date on which a member was created, in YYYY/MM/DD format.
If the input data set is a PDS(E), you may specify this parameter, or specify a range of creation dates with the CRESTART and CREEND keywords.
You can specify an asterisk (*) as the last character to indicate a range of dates or a percent sign (%) in place of a single character to indicate a selection of dates.
created is ignored if the data set is not a PDS.
- CRESTART=crestart
- The start of a range of creation dates in YYYY/MM/DD format to
be included in the copy.
If CRESTART is specified but CREEND is omitted, all members of the PDS(E) from the crestart value onwards are included.
If omitted, or you do not enter a full date, or you specify an asterisk (*) as the last character, the unspecified portion of crestart defaults to the right as follows:- DD
- = 01
- MM
- = 01
- YYYY
- = 0000
- CREEND=creend
- The end of a range of creation dates in YYYY/MM/DD format to be
included in the copy. If omitted, or you do not enter a full date, or you specify an asterisk (*) as the last character, the unspecified portion of creend defaults to the right as follows:
- DD
- = 31
- MM
- = 12
- YYYY
- = 9999
- CHANGED=changed
- The date on which a member was last modified, in YYYY/MM/DD format.
If the input data set is a PDS(E), you may specify this parameter, or specify a range of modification dates with the CHGSTART and CHGEND keywords.
You can specify an asterisk (*) as the last character to indicate a range of dates or a percent sign (%) in place of a single character to indicate a selection of dates.
changed is ignored if the data set is not a PDS.
- CHGSTART=chgstart
- The start of a range of modification dates in YYYY/MM/DD format
to be included in the copy.
If CHGSTART is specified but CHGEND is omitted, all members of the PDS(E) from the chgstart value onwards are included.
If omitted, or you do not enter a full date, or you specify an asterisk (*) as the last character, the unspecified portion of chgstart defaults to the right as follows:- DD
- = 01
- MM
- = 01
- YYYY
- = 0000
- CHGEND=chgend
- The end of a range of modification dates in YYYY/MM/DD format
to be included in the copy. If omitted, or you do not enter a full date, or you specify an asterisk (*) as the last character, the unspecified portion of chgend defaults to the right as follows:
- DD
- = 31
- MM
- = 12
- YYYY
- = 9999
- USERID=userid
- The TSO user ID by which the member was last updated.
If the input data set is a PDS(E), you may specify this parameter, or specify a range of user IDs with the UIDSTART and UIDEND keywords.
You can enter a generic user ID by using asterisks and percent signs.
userid is ignored if the data set is not a PDS.
- UIDSTART=uidstart
- The start of a range of user IDs to be included in the copy.
If UIDSTART is specified but UIDEND is omitted, all members of the PDS(E) from the uidstart value onwards are included.
If omitted, or you do not enter a full 7-character user ID, or you specify an asterisk (*) as the last character, File Manager replaces the asterisk and pads the unspecified portion of uidstart to the right with low values (X'00').
- UIDEND=uidend
- The end of a range of user IDs to be included in the copy.
If you omit this field, it defaults to high values (X'FF').
If you specify less than 7 characters (without an asterisk as the last character), File Manager pads uidstart to the right with low values (X'00'). If you specify an asterisk (*) as the last character, File Manager replaces the asterisk and pads the unspecified portion of uidend with high values (X'FF').
- CPYMBR
- Provides a means of selecting input members from a PDS(E) where
no generic name pattern and no member name range has been specified.
Also provides a means for renaming the selected members as they are
copied to the output data set. If the CPYMBR keyword is specified,
only those members included in the CPYMBR arguments are copied to
the output data set. Members selected by the MEMBER=member1 that
are not included in the CPYMBR arguments are not copied.
The CPYMBR arguments also refine the member list specified in the MEMBER=member1 parameter. If the MEMBER keyword is not specified, it is assumed to be MEMBER=*, and all members named in the CPYMBR list are processed. However, if the MEMBER keyword is specified, for example as MEMBER=TEST*, the members included in the CPYMBR list are selected from the TEST* subset of members. Any members named in the CPYMBR arguments that do not match the mask given in the MEMBER parameter are not copied.
- from_mem
- The name of the member to be copied. Generic name masks are allowed.
- to_mem
- The name of the member after it has been copied to the output data set. If unspecified, the output member is not renamed.
Note: See Usage notes. - BINRECIN=binrecin-len
- Specifies the record length used for processing the
From
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).
- USEIOXIN
- Specifies whether to invoke a user I/O exit, to process the input
data set.
- NO
- Default. Do not invoke a user I/O exit.
- YES
- Invoke a user I/O exit to process the input 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.
- IOXIN
- Specifies the name of the user I/O exit used for the input 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 USEIOXIN=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 USEIOXIN has been set to
YES and no installation default has been provided, you must specify
IOXIN=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.
- EXCLUSIVE
- Note: This option is supported for backward compatibility only.Determines the disposition of the From (input) data set.
Use the new DIRINTEGR option.
- NO
- Default. The data set is allocated with DISP=SHR, so that other users can obtain concurrent access to a PDS or PDSE during execution of DSC.
- YES
- The data set is allocated with DISP=OLD, preventing concurrent
access to the PDS or PDSE. Note: If you pre-allocate the input data set with DISP=SHR and then specify,EXCLUSIVE=YES in batch, I/O errors might occur during concurrent access to the data.
- DIRINTEGR
- Specifies whether to invoke a user I/O exit to process the input
data set.
- NO
- Default. File Manager uses a faster PDS(E) directory processing method. This may cause I/O errors when multiple users are concurrently updating the directory of the data set being processed.
- YES
- File Manager uses safer, but slower, PDS(E) directory processing method. This method allows for safe concurrent updates of the PDS(E) directory by multiple users.
- INCLUDEMD
- This parameter determines what happens to the descriptor for an
Websphere MQ message.
- YES
- The descriptor is added as a prefix as the data is copied.
- NO
- Just the message data is copied. This is the default.
This parameter applies only when the input describes an MQ queue.
- JCL=NO
- Treat the data set as a non-JCL data set.
- JCL=YES
- Indicates the file or PDS(E) members being copied contain JCL,
the syntax of which is to be maintained during the copy process.
This option is only available when the PROC option is selected as changes can only be made to the input data by means of REXX processing.
This option is ignored if a template is being used.
Use of this option may affect the performance of the copy due to the overhead of verifying the syntax of the JCL.
- OUTPUT=ddname
- Defines a reference to a DD or TSO ALLOC statement for the “To”
data set or HFS file. The default is
DDOUT. - DSNOUT=dsname
- Defines the name of the “To” data set or an absolute
path to the
To
HFS file (directory). 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. You can further describe this data set, as follows:- (member2)
- 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. 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 over more than one line.
- VOLSEROUT=volser
- Volume serial number for a new or non-cataloged “To” data set.
- DATACLAS=value
- The name of a data class defined in your SMS installation. Do not enter a value on a system without SMS.
- STORCLAS=value
- The name of a storage class defined in your SMS installation. Do not enter a value on a system without SMS.
- MGMTCLAS=value
- The name of a management class defined in your SMS installation. Do not enter a value on a system without SMS.
- BINRECOUT=binrecout-len
- Specifies the record length used for processing the
To
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).
Note: See Usage notes. - 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.
- MEMOUT=mask
- Where a number of input members have been specified, you can specify
a member name pattern for the output members, allowing you to rename
your members as they are copied. The member name pattern can consist
of any characters that are valid in a member name and two special
pattern characters: the asterisk (*) and percent sign (%).
- Asterisk (*)
- The asterisk is a place-holding character that means multiple
characters with no change. Only one asterisk should appear in the
mask. Any subsequent asterisk characters are treated as percent signs.
For example, if you enter:
ABC*The renamed members all begin with ABC followed by the remainder of the old member name.
- Percent sign (%)
- The percent sign is a place-holding character that means a single
character with no change. As many percent symbols as necessary may
appear anywhere in a member name. For example, if you enter:
The 1st 3 characters of the renamed members remain unchanged, the 4th character is replaced with the letter “A” and the remainder of the old member name remains unchanged.%%%A*
- MQOPEN
- This parameter determines if the Websphere MQ queue is opened
in browse or share mode and the messages from that queue read in a
destructive manner.
- BROWSE
- The Websphere MQ queue is opened in browse mode. Messages are not removed from the queue as they are read. This is the default.
- SHARE
- The WebSphere MQ queue is opened in share mode. Messages are removed from the queue as they are read (the queue is read in a destructive manner).
This applies only when the input describes an MQ queue.
- 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.
- STATS=ON
- Default. This updates the ISPF statistics (if already present) when a PDS or PDSE member has been changed.
- STATS=OFF
- The ISPF statistics are not updated when a PDS or PDSE member has been changed.
- STATS=FORCE
- The ISPF statistics that exist for members being processed are always updated and statistics for a member that previously did not have statistics are created.
- DISP
- Determines the disposition of the To (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: MOD is not available for PDS(E) member processing.
Note: SMS might modify the allocation of new data sets on your system. For details, contact your SMS Administrator. - POSITION=skip
- Number of logical records to be skipped from the beginning of the data set. The default is 0.
- SMPLINCL=sample_include
- Number of physical records to be included in a repeating sample from a data set. Both SMPLINCL and SMPLSKIP keywords must have non-zero values for sampling to take effect. Range: 0–9999999.
- SMPLSKIP=sample_skip
- Number of physical records to be skipped in a repeating sample from a data set. Both SMPLINCL and SMPLSKIP keywords must have non-zero values for sampling to take effect. Range: 0–9999999.
- KEY=key (VSAM only)
- A key for KSDS records, or a slot number for RRDS records. The
maximum key length is 30 characters. The first record with a key or
slot value greater than or equal to key is
the first record copied. If you omit the key and skip values,
copying begins with the first record in the data set.
If the key contains lowercase characters, blanks, or commas, enclose it in quotation marks. You can also specify a key in hexadecimal format (for example, X'C1C2C3').
- NLRECS
- Number of records to be copied or ALL.
- ALL
- If you specify ALL or omit the parameter, all the remaining records are copied.
- nlrecs
- The maximum number is 999 999 999.
When you are coding a REXX procedure and NLRECS is specified, then this can affect the number of records presented to the REXX procedure. NLRECS only applies to the number of records written to the primary output data set. It does not apply to records written in the REXX procedure with the WRITE() function.
- CORRESP
- Specifies whether or not File Manager maps output fields to input
fields with the corresponding name. The default is NO.
- NO
- Instructs File Manager to use the existing field mapping in the TCOUT member. If the TCOUT member is a copybook, or no field mapping is supplied, then File Manager ignores this option and performs a corresponding copy (as if you had specified CORRESP=YES).
- YES
- Instructs File Manager to map output fields to input fields with
the corresponding name.
If you want to use existing mapping in the “To” template, specify CORRESP=NO.
- REPLACE
- Specifies whether or not File Manager replaces like-named members
in an output partitioned data set. The default is NO.
- NO
- Like-named members in the output partitioned data set are not replaced.
- YES
- Like-named members in the output partitioned data set are replaced.
- IGNLEN
- Specifies whether or not File Manager ignores length mismatches
when selecting records for processing.
- NO
- Do not ignore length mismatches. Records that are shorter than the matching structure length in the template are not selected for processing.
- YES
- Use this option to ignore length mismatches.
When a field in the “From” template spans or is beyond the copied record's boundary, the corresponding field on the output record is initialized (since there is no data available from the from field). The exception is alphanumeric fields, where the portion of the field that exists on the input record is copied (a partial copy) and the remainder of the output field is padded with blanks.
- RECCOUNTS
- Controls whether or not the count of records for copied PDS(E)
members and sequential/VSAM data sets is printed in the processing
listing in batch.
- NO
- Record counts are not reported.
- YES
- Record counts are reported. Note: This option affects PDS(E) processing ONLY. For sequential/VSAM data sets, the record counts are always provided. When the option is selected, it prevents the use of IEBCOPY for PDS(E) processing, which may affect the copy performance.
- PACK
- Determines if File Manager should detect if the input data is
in ISPF packed format and specifies if the output data is to be written
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.
- ASIS
- Instructs File Manager to write the output in ISPF Packed format only if the input is in ISPF packed format.
- PACK
- Instructs File Manager to write the output in ISPF packed format regardless of the input format.
- UNPACK
- Instructs File Manager to write the output without ISPF packing, regardless of the input format.
- NONE
- Instructs File Manager not to determine if the input data set is in ISPF packed format and writes the output records as they are read from the input data set (after any enhanced processing).
- SKIP
- Instructs File Manager to determine if the input data set is in ISPF packed format and if so, to skip the copy processing.
- PROC=proc
- Member name of a REXX procedure that you want to use to process each
record before it is copied, or an asterisk (*) to indicate the procedure
is inline. If you specify a member name, you must define an
FMNEXEC ddname that identifies the
PDS containing the member. If you specify *, the procedure is read from
SYSIN immediately following the control statement for the current function.
The inline procedure is terminated by a record containing a slash and a
plus sign (/+) in columns 1–2.
For more information about using DFSORT or REXX procedures to process records before they are copied, see Enhancing File Manager processing.
If PROC=proc is specified, you can then choose to include a MEMPROC parameter:
- MEMPROC
- Specifies that REXX member selection is in effect. Records are read
from the input member and then cached in memory until a decision is made,
within the REXX procedure, on whether the member is to be copied or dropped.
Once the decision has been made, the entire member is either copied or
dropped, depending upon the RETURN string specified in the REXX procedure.
If the entire member is processed without encountering a RETURN DROP MEMBER or RETURN PROCESS MEMBER string, the member is processed according to the action specified by the parameter specified for MEMPROC. These are:
- PROCESS
- The member is to be included in the copy. The member is copied
intact, subject to any specified template processing, which is performed
before the user REXX proc is invoked.
This is the default action, if no parameter is specified with the MEMPROC keyword.
- DROP
- The member is to be excluded from the copy. Processing continues with the next member.
- INRDW
- Controls whether or not to adjust the input start location when
the specified start location takes into account the record descriptor
word (RDW).
- NO
- Does not adjust the input start location.
- YES
- Subtracts 4 from all start locations that have been coded on external functions that refer to the input record.
- OUTRDW
- Controls whether or not to adjust the output start location when
the specified start location takes into account the record descriptor
word (RDW).
- NO
- Does not adjust the output start location.
- YES
- Subtracts 4 from all start locations that have been coded on external functions that refer to the output record.
- Template options
- The template options define which templates (if any) are used
to describe the record structure in the “From” and “To”
data sets, and how File Manager processes those templates.
- TINPUT=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 input data. The default is TDDIN.
If you specify a concatenated DD, then you must provide the member name, member.
Note: When you specify concatenated data sets in the template DD statement, and these data sets are vendor-managed copybook libraries, a maximum of 20 data sets are supported. - TINMEM=member
- The name of the copybook or template member in the data sets identified by the TINPUT parameter if it has not been specified on the DD statement. This parameter must not be specified if the TCIN parameter is specified.
- TCIN=tcin(member)
- PDS and member name of the copybook or template that describes the record structure of your input data.
- OFFSETIN
- The length of the 01 field in the “From” 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 “From” template.
- ALL
- Where the template contains multiple record structures, this keyword
applies the corresponding value to all Level
01 within the “From” 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 to be applied. The default is the first Level 01 field in the “From” 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 data sets 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 “To” 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
- 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.
For details on the effect of these compiler options, see the HLASM V1R6 Programmer's Guide.
- External format processing
- When generating the output in an external format such as XML or CSV, File Manager uses the following options:
- FORMAT
- Specifies the external format to be used for output.
- XML
- Indicates that XML format is used.
- CSV
- Indicates that CSV format is used.
- NPRTCHAR
- Determines how non-printable characters are to be represented in the output.
- '.' (dot)
- Default. Each non-printable character is replaced with ".".
- ASIS
- Non-printable characters appear unchanged in the output.
- HEX
- Any non-printable character is converted into its hexadecimal representation.
- 'replacing-character-1'
- Each non-printable character is replaced with the replacing-character-1. The set of allowable
characters is limited to printable characters with exception of special characters. You may specify:
- char
- A character, such as "?".
- C'char'
- A character used without case translation.
- X'cc'
- A character defined by its hexadecimal value.
- NESTHEX
- Each string of consecutive non-printable characters will be nested into content of element as X'hex-representation-of-string- of-non-printable-characters'
- SKIP
- Any non-printable character causes the value to be skipped (data is represented by start and end tags, without any content).
- SPECCHAR
- Determines how special characters are to be represented in the XML output.
- '_' (underscore)
- Default. Each special character is replaced with "_".
- ESCAPE
- Special characters are converted into escaped strings:
- ">" for ">"
- "<" for "<"
- "'" for "'"
- """ for "'"
- "&" for "&"
- CDATA
- Unchanged string containing special characters are enclosed into the CDATA section.
- HEX
- Any special character will cause the XML value to be converted into its hexadecimal representation.
- 'replacing-character-2'
- Each special character is replaced with the replacing-character-2. The set of allowable
characters is limited to printable characters with exception of special characters. You may use:
- char
- A character, such as "?".
- C'char'
- A character used without case translation.
- X'cc'
- A character defined by its hexadecimal value.
- NESTHEX
- Each string of consecutive special characters is nested into content of element as X'hex-representation-of-string-of-special-characters'
- INVDATA
- Determines how invalid data is to be represented in the output.
- '*' (asterisk)
- Default. Invalid data is represented by string of "*" with a length equal to the assumed length of the output value.
- HEX
- Invalid data causes the output value to be a hexadecimal representation of the input value.
- 'replacing-character-3'
- Invalid data is represented by a string of replacing-character-3 with
a length equal to the assumed length of the output value. The set of allowable characters is limited
to printable characters with exception of special characters. You can use:
- char
- A character, such as "?".
- C'char'
- A character used without case translation.
- X'cc'
- A character defined by its hexadecimal value.
- SKIP
- Invalid data is skipped (data is represented by start and end tags, without any content).
- INDENT
- Specifies the number of blanks used to indent each level of XML tag corresponding to the nested
level in the template or copybook.
- 1
- Default. Each nested level causes an increase in indentation of each XML level by one blank.
- indent-step
- Any value from 0 to 9. INDENT=0 will force no indentation. Each positive number will cause an increase in indentation of each XML level by this number of blanks.
- FILLERS
- Indicates whether fillers (unnamed data elements) are to be included into the output or not.
- NO
- Default. Fillers are ignored (not represented in the output).
- YES
- Fillers are treated as named data elements and represented in the output.
- REDEFINES
- Indicates whether data elements redefining other data elements are to be included into the
output or not.
- NO
- Default. Redefines are ignored (not represented in the output).
- YES
- Redefines are treated as other data elements and represented in the output.
- UNICODE
- Indicates whether the output is to be converted to Unicode or not.
- NO
- Default. The output is not converted.
- YES
- The output is converted to Unicode.
- LINESPLIT
- Indicates, whether the output lines resulting from processing an input record are spanned
contiguously over multiple output records, or each output line must be included as the only line in
an output record.
- NO
- Default. Output line is contained, as the only output line, in one output record.
- YES
- Output records are cut independently of external formatting. An output line can span multiple output records and not necessarily start from the beginning of the record. However, output representation of each input record starts from the new output record.
- HEADINGS
- Indicates whether to include field names as headings in the first line of CSV output.
- NO
- Default. Field headings are not included in the output.
- YES
- Field headings are included in the output.Note: Field headings will be produced when a layout changes or the headings required for subsequent value fields change.
- LEADING
- Indicates whether to preserve leading blanks in field values.
- NO
- Default. Leading blanks are ignored (not represented in the output).
- YES
- Leading blanks are included in the output.
- TRAILING
- Indicates whether to preserve trailing blanks in field values.
- NO
- Default. Trailing blanks are ignored (not represented in the output).
- YES
- Trailing blanks are included in the output.
- LZERO
- Indicates whether leading zeros in numeric fields are to be included in the CSV output.
- NO
- Default. Leading zeros are removed unless the field definitions in the associated template specify leading zeros as YES.
- YES
- Format numeric fields with leading zeros.
- QUOTED
- Indicates whether all CSV values are to be encapsulated in quotes.
- NO
- Default. Values are only encapsulated if escaping is required or if a field contains the delimiter character.
- YES
- All CSV values are encapsulated in quotes.
- SNGLQUOTE
- Indicates whether to use single quotation marks or double quotation marks to wrap output field values.
- NO
- Default. Use double quotation marks for quoted values.
- YES
- Use single quotation marks for quoted values.
- DELIM
- Specifies an alternate character to delimit fields in the output file. The default character is
a comma. The character will be uppercased unless it is specified in one of the following formats:
- C'char'
- A character used without case translation.
- X'cc'
- A character defined by its hexadecimal value.
Note: You cannot specify different options for compiling “From”
and “To” copybooks; the same copybook options are used
for both.
//DSC JOB (acct),'name'
//* Copy data set to data set
//*
//FMBAT PROC
//FMBAT EXEC PGM=FILEMGR
//STEPLIB DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
// PEND
//*
//STPSSEX EXEC FMBAT
//SYS1INP DD DISP=SHR,
// DSN=SYS1.PARMLIB(LNKLST00)
//SYSIN DD *
$$FILEM VER
$$FILEM DSC INPUT=SYS1INP,
$$FILEM DSNOUT=FMNUSER.TEMP.LINKLIST,
$$FILEM TCIN=FMNUSER.FMN.TEMPLATE(ODOTWO01)
$$FILEM EOJ
/*This example copies all members of the input PDS ('USERID.PLXIN') that match the input mask 'XYZE*' to the output PDS('USERID.PLXOUT'), renaming them using the rename mask JBG*. The members XYZEDIT, XYZEDIT1, XYZEDIT2, XYZEDIT3, XYZEDIT4, XYZEDIT5 and XYZEDIT6 are copied and renamed as JBGEDIT, JBGEDIT1, JBGEDIT2, JBGEDIT3, JBGEDIT4, JBGEDIT5 and JBGEDIT6 respectively.
//SYSIN DD *
$$FILEM DSC DSNIN=USERID.PLXIN,
$$FILEM MEMBER=XYZEDIT*,
$$FILEM DISP=MOD,
$$FILEM DSNOUT=USERID.PLXOUT,
$$FILEM MEMOUT=JBG*This example copies a PDS using a TSO environment. This is required for load module processing when File Manager is not APF-authorized and recommended for better performance with a PDS or PDSE.
//FMBAT EXEC PGM=IKJEFT01,DYNAMNBR=100
//STEPLIB DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
CALL *(FMNMAIN)
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
$$FILEM DSC DSNIN=TEST.PDS,
$$FILEM MEMBER=*,
$$FILEM REPLACE=YES,
$$FILEM DISP=OLD,
$$FILEM DSNOUT=TEST2.PDS