DSU (Data Set Update) -- batch only

Purpose
Update disk data set records.
Usage notes
Use this function to update logical records in a single sequential disk data set, a single VSAM data set, one or more members of a PDS, an MQ queue, or a CICS® resource.
Note: Compressed non-VSAM extended format data sets (compressed PSE data sets) are not supported (for use with DSU). It is recommended that you use FCH with a PROC if you want to update compressed data sets with a PROC.
You can select the records to be processed using:
  • Member name selection criteria
  • Date created selection criteria
  • Date last modified selection criteria
  • User ID selection criteria

Records in the data set are read sequentially. After each record is read, File Manager invokes the REXX procedure specified in the PROC parameter, and passes the contents of the record to the exec. The contents are passed in two File Manager-defined REXX variables, INREC and OUTREC. When the exec is invoked, the contents of the two variables are identical. The INREC variable is intended to be used as a reference variable. Any changes made to it are ignored by File Manager. The OUTREC variable can be updated by the exec. After the REXX procedure has processed the record, if the data in OUTREC has changed, the record is updated in the data set using the contents of OUTREC.

You cannot add records or delete records using DSU. If you need to add or delete records, you can use one of the File Manager data set copy functions. You cannot change the length of records in a data set using DSU. If the REXX procedure increases the length of the data in OUTREC, the data is truncated to its original length before the record is updated. If the REXX procedure decreases the length of the data in OUTREC, the data is padded to its original length using the pad value specified in the PAD processing option. If no pad value has been specified, the contents of the record are unpredictable.

Performance tips
  • When you use DSU to update members of a PDS(E):

    One DSU default is STATS=ON, which causes the ISPF statistics for each updated member to be updated. This can significantly increase I/O (EXCP) and CPU utilization. To improve performance, consider using STATS=OFF.

Options
When you specify the PROC option, you are supplying a REXX procedure. For more information, see the proc parameter below.
Return codes
The default return codes from the DSU function have the following modified meanings:
1
One or more members not updated
2
Change failed (for example invalid key change)
4
No records updated (NOUPDATE=NO)
4
No records processed because no members to process
4
No records processed because input empty
4
No records processed because input is in ISPF Packed Data format and the “PACK=STOP” option was specified.
8
REXX non-syntax error encountered while processing records
16
Program Object specified - this is not supported
16
Data set or member in use
16
Data set or member open error
16
Data set not found
16
Other input or output error occurred
16
Insufficient storage available
16
DSU 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
DSEB
Edit a data set via batch job processing.
DSX
Display the extents of a data set.
Figure 1. Syntax

1 DSU
1! INPUT=DDIN
1 INPUT=ddname
1 DSNIN=dsname?VOLSERIN=volser
1 rt:applid:rname
1! NOUPDATE=NO
1 NOUPDATE=YES
1 ? MEMSTART=startstring? MEMEND=endstring
1 MEMBER=member1
4? XMEMBERS=(+ ,xmem_filter)
1! INRDW=NO
1 INRDW=YES
1! OUTRDW=NO
1 OUTRDW=YES
1 ? CRESTART=crestart? CREEND=creend
1 CREATED=created
1 ? CHGSTART=chgstart? CHGEND=chgend
1 CHANGED=changed
1 ? UIDSTART=uidstart? UIDEND=uidend
1 USERID=userid
1! POSITION=0
1 POSITION=skip
1 KEY=key
1! NLRECS=ALL
1 NLRECS=nlrecs
1! PACK=STOP
1 PACK=CONTINUE
1! STATS=ON
1 STATS=OFF
1 STATS=FORCE
1! USEIOXIN=NO
1 USEIOXIN=YES
2.1! IOXIN=sysexit
2.1? IOXIN=ioxname
14 PROC=proc
14?  %Template processing options
Template processing options

1! TINPUT=TDDIN
1 TINPUT=ddname?TINMEM=member
1 TCIN=tcin(member)
2? OFFSETIN=(
3.1 value?,ALL
3.1 ?value,ALL,+ ,value,fieldname
2)
2? MEMLIST=(+ ,member_n)
2?  %Copybook processing options
Copybook processing

1! LANG=AUTO
1 LANG=
2.1 COBOL
2.1 PLI
2.1 HLASM
1  %COBOL options
1  %PL/I options
1  %HLASM options
COBOL options

1! DBCS=NO
1 DBCS=YES
1! CDPC=NO
1 CDPC=YES
1! CAE=NO
1 CAE=YES
1 +  RFROMn=operand1 RTOn=operand2
1! CBLMAXRC=4
1 CBLMAXRC=num
1 CBLLIBS=(+  dsname)
7? CBLADDOP=options
PL/I options

1! BIN63=NO
1 BIN63=YES
1! DEC31=NO
1 DEC31=YES
1! GRAPHIC=NO
1 GRAPHIC=YES
1! UNALIGNED=NO
1 UNALIGNED=YES
1! PLIMAXRC=4
1 PLIMAXRC=num
1 PLILIBS=(+  dsname)
7? PLIADDOP=options
HLASM options

1! DBCS=NO
1 DBCS=YES
1! NOALIGN=NO
1 NOALIGN=YES
1! ASMMAXRC=4
1 ASMMAXRC=num
1 ASMLIBS=(+  dsname)
5? ASMADDOP=options
INPUT=ddname
Defines a reference to a DD or TSO ALLOC statement for the input data set. The default is DDIN.
DSNIN=dsname
Defines the name of the input data set. 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:
VOLSERIN=volser
Volume serial number for a non-cataloged data set.
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.
NOUPDATE
Allows you to specify that you intend no updates to the data set while executing the utility.
NO
Updates to the data are honored.
YES
Forces the allocation of the data set as input only. All updates to the data are ignored.
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 range of member names with the MEMSTART and 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.

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.
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.
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 format x'hex-digits'.

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.
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
No other wildcarding is allowed.
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
No other wildcarding is allowed.
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
No other wildcarding is allowed.
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
No other wildcarding is allowed.
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').

POSITION=skip
Number of logical records to be skipped from the beginning of the data set. The default is 0.
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 updated. If you omit the key and skip values, updating 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 printed or ALL.
ALL
If you specify ALL or omit the parameter, all the remaining records are copied.
nlrecs
The maximum number is 99 999 999.
PACK
Determines if File Manager should detect if the input data is in ISPF packed format.
STOP
Default. File Manager detects whether the input data is in ISPF packed format, and if it is, stops the processing.
CONTINUE
File Manager does not detect whether the input data is in ISPF packed format and continues processing.
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 is 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.
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.
PROC=proc
Member name of a REXX procedure that you want to use to process each record before it is updated, or an asterisk (*) to indicate the REXX 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 REXX procedures to process records before they are updated, see Enhancing File Manager processing.

Template processing
Define which template (if any) is used to describe the record structure in the input data set, and how File Manager processes this template.
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.

TINMEM=member
The name of the copybook or template member in the datasets 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.
Note: If you specify a template for DSEB and DSU, it is ignored, except for calls to the external REXX function PRINT specifying TABL or SNGL format.
OFFSETIN
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 template.
ALL
Where the template contains multiple record structures, this keyword applies the corresponding value to all Level 01 fields within the 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 template.
MEMLIST
Allows you to specify a list of member names.
member_n
The name of the member to be processed. Generic name masks are allowed.
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 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 File Manager 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.
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
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.

//DSU JOB (acct),'name'  PDS Member Update
//*
//FMBAT    PROC
//FMBAT    EXEC PGM=FILEMGR
//STEPLIB  DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//         PEND
//*
//FILEMGR  EXEC FMBAT
//FMNTSPRT DD SYSOUT=*
//JCLPDS   DD DSN=FMNUSER.FMOS390.JCL,DISP=SHR
//SYSIN    DD *
$$FILEM DSU INPUT=JCLPDS,MEMBER=*,PROC=*
/* Translate all records to uppercase */
Upper outrec
Return
/+
$$FILEM EOJ
/*
//DSU JOB (acct),'name'  Fix post code
//*
//FMBAT    PROC
//FMBAT    EXEC PGM=FILEMGR
//STEPLIB  DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//         PEND
//*
//FILEMGR  EXEC FMBAT
//FMNTSPRT DD SYSOUT=*
//SYSIN    DD *
$$FILEM DSU DSNIN=FMNUSER.FMOS390.TRANRECS,
$$FILEM     PROC=*
/* Locate name and address record for James  */
/* Browne and change postcode, stored in     */
/* packed decimal, from 6011 to 6194         */
If Substr(inrec,1,1) == 'A' &
   Substr(inrec,32,5) == 'James' &
   Substr(inrec,57,6) == 'Browne' then
   outrec = Change(outrec,'06011F'x,'06194F'x,1,125,3)
Return
/+
$$FILEM EOJ
/*