FCH (Find/Change)

Purpose
The FCH function allows you to:
  • Search for, and optionally change, strings in a PDS, VSAM data set, sequential data set, MQ queue, or CICS® resource.
  • Search for strings in HFS files.
Usage notes
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

You can either specify a REXX procedure with the proc parameter, or enter a FIND or CHANGE command in the Command line. For information about the primary commands, see Finding and changing data in multiple PDS members. The LOCATE primary command is ignored in batch jobs. When working with compressed non-VSAM extended format data sets (compressed PSE data sets), the CHANGE command is not supported, however, the FIND command can be used.

Multiple command processing

There is no limit on the number of FIND or CHANGE commands that can be processed in one pass of the file, but each FIND or CHANGE command must start on a new line. Be careful when using overlapping change commands such as C cat dog and C catapult crossbow. A string is only matched against the first command with a matching search argument. Therefore, you must place the longer change first. For example, if you specify the following change commands:

C Cat Dog
C Catapult Crossbow

The second command would never get processed. Reversing the command order would ensure any occurrences of “Catapult” were changed.

After a change is made, FCH processing continues for the same data record. The point where processing resumes is immediately following the most recently changed string. As a result, changes are not recursive, so that C cat cow and C cow dog does not change “cat” to “dog”, unless separate runs are done. Furthermore, if the search argument is found but the change fails, subsequent FIND or CHANGE commands that match that string are not done.

Data sets containing variable length records

If a CHANGE command would result in an increase in the length of a variable length record, the change is not processed.

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

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

  • Using JCL processing (JCL=YES) is more CPU intensive than JCL=NO. Only use JCL=YES if necessary.
  • You can improve concurrent read access by other users or jobs to the target data set when there is a user PROC, by using the NOUPDATE=YES option when the PROC will not be performing any updates.
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 FCH function have the following modified meanings:
1
One or more FIND or CHANGE commands successful but one or more FIND or CHANGE commands unsuccessful because no strings found.
2
One or more strings found but one or more CHANGE commands could not be performed (no space available or invalid key change).
4
No FIND or CHANGE command successful because no strings found (no matches).
4
No FIND or CHANGE command successful because no members to process.
4
No FIND or CHANGE command successful because input empty.
8
Bad FIND/CHANGE command(s) supplied.
8
Too many FIND/CHANGE commands supplied.
8
REXX error encountered.
8
Job step interrupted/cancelled.
16
Program Object not supported (but specified).
16
Data set in use.
16
Member in use.
16
Data set/member open error.
16
Data set not found / allocation error.
16
Insufficient storage available.
16
Input data appears ISPF packed but is not valid.
16
FCH abended.
16
Other serious error that stops processing occurred (for example an input/output error).
Note: Return codes can be customized during installation. If you receive return codes that do not match those listed above, your site might have customized the return codes for this function. Z Data Tools may also issue the 999 abend, if the return code in batch is equal to or greater than the ABENDCC value. Contact your Z Data Tools systems administrator for details.
Related functions
DSEB
Edit a data set via batch job processing
TRS
Locate data within a tape file
Read syntax diagramSkip visual syntax diagram
Syntax

        .-INPUT=DDIN-----------------------.   
>>-FCH--+----------------------------------+-------------------->
        +-INPUT=ddname---------------------+   
        +-DSNIN=dsname-+-----------------+-+   
        |              '-VOLSERIN=volser-' |   
        '-rt:applid:rname------------------'   

>--+-+----------------------+--+------------------+-+----------->
   | '-MEMSTART=startstring-'  '-MEMEND=endstring-' |   
   '-MEMBER=member1---------------------------------'   

>--+-+-------------------+--+---------------+-+----------------->
   | '-CRESTART=crestart-'  '-CREEND=creend-' |   
   '-CREATED=created--------------------------'   

>--+-+-------------------+--+---------------+-+----------------->
   | '-CHGSTART=chgstart-'  '-CHGEND=chgend-' |   
   '-CHANGED=changed--------------------------'   

>--+-+-------------------+--+---------------+-+----------------->
   | '-UIDSTART=uidstart-'  '-UIDEND=uidend-' |   
   '-USERID=userid----------------------------'   

>--+------------+--+------------------------+------------------->
   '-NLRECS=num-'  '-BINRECIN=record-length-'   

   .-USEIOXIN=NO--------------------.  .-JCL=NO--.   
>--+--------------------------------+--+---------+-------------->
   |              .-IOXIN=sysexit-. |  '-JCL=YES-'   
   '-USEIOXIN=YES-+---------------+-'                
                  '-IOXIN=ioxname-'                  

                                   .-LIST=LONG----.   
>--+----------------------------+--+--------------+------------->
   |           .-NOUPDATE=NO--. |  '-LIST=SUMMARY-'   
   '-PROC=proc-+--------------+-'                     
               '-NOUPDATE=YES-'                       

                 .-STATS=ON----.  .-EXCLUSIVE=NO--.   
>--+----------+--+-------------+--+---------------+------------->
   +-DBCS=NO--+  +-STATS=OFF---+  '-EXCLUSIVE=YES-'   
   '-DBCS=YES-'  '-STATS=FORCE-'                      

   .-DIRINTEGR=NO--.  .-PACK=ASIS--------.   
>--+---------------+--+------------------+---------------------><
   '-DIRINTEGR=YES-'  '-PACK=-+-PACK---+-'   
                              +-UNPACK-+     
                              +-NONE---+     
                              '-SKIP---'     

INPUT=ddname
Defines a reference to a DD or TSO ALLOC statement for the input data set, or HFS file. The default is DDIN.
DSNIN=dsname
Defines the name of the input data set, or an absolute path to a 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:
VOLSERIN=volser
Volume serial number for a non-cataloged data set.

An absolute path to a HFS file (directory) must be enclosed in apostrophes. If it does not fit on one line, it can be split into several lines.

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 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.
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, Z Data Tools 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), Z Data Tools pads uidstart to the right with low values (X'00'). If you specify an asterisk (*) as the last character, Z Data Tools replaces the asterisk and pads the unspecified portion of uidend with high values (X'FF').

NLRECS=num
Specifies the number of records to be processed in each data set or member.
BINRECIN=record-length
Specifies the record length used for processing a 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 Z Data Tools 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 Z Data Tools 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, Z Data Tools 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 Z Data Tools in the STEPLIB concatenation.
JCL=NO
Treat the data set as a non-JCL data set.
JCL=YES
The data set contains JCL and the JCL syntax is to be preserved.

The columns searched are set to 3 through 71, unless the statement is not a JCL statement. A statement is considered to be a JCL statement if it begins with the strings "/*" or "//". If the statement does not begin with either of these strings, it is not considered to be a JCL statement in which case any column range specified on the FIND (or CHANGE, respectively) command or preset using the BOUNDS command is honored. If no column range has been specified, the full record is searched.

If not successful at maintaining the number and size of records, Z Data Tools attempts to rewrite the file:
  • More errors are possible in this case. For example, a PDS(E) may run out of room.
  • If a logical line is changed and requires more physical records, the file is rewritten. The data in columns 73–record length for new physical records is copied from the last related original physical record. Data past column 72 is treated as non-changeable sequence numbers or comments.
PROC=proc
Member name of a REXX procedure that you want to use to process each record, or an asterisk (*) to indicate the procedure is inline. If you specify a member name, you must define an HFMEXEC 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.

Whether or not a record appears in the FCH report is determined by the return code from the REXX procedure for that record. (If no PROC statement is specified, one is assumed at the end of the $$FILEM control statements.) If the REXX procedure ends with a RETURN DROP statement, then the current record is considered to be “not selected” (not one of the records you wanted to find), and does not appear in the FCH report. If the REXX procedure ends normally, or with an explicit RETURN (without the DROP keyword), then the current record is considered to be “selected”, and is included in the FCH report. Records that have been selected without being changed by the REXX procedure are marked in the FCH report by an “s” suffix attached to their record number, while records that have been selected and changed are marked by a “c”.

In a REXX procedure for FCH, explicitly code a RETURN statement when you identify a record that you want to select. To ensure that other records are not selected, on the last line of the REXX procedure, code a RETURN DROP statement.

For more information about using REXX procedures to process records, see Enhancing Z Data Tools processing.

NOUPDATE
Allows you to specify that you intend no updates to the FCH data set while executing the utility. This option is valid only when a REXX procedure has been specified and is ignored otherwise.
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.
LIST=LONG
Default. This prints each record where the string was found as well as a summary report.
LIST=SUMMARY
This produces a summary report only.
DBCS=YES
(Default for LANGUAGE=JAPANESE). This processes and preserves DBCS shiftin and shiftout characters within the data records.
DBCS=NO
(Default for LANGUAGE=ENGLISH). This ignores DBCS shiftin and shiftout characters within the data records.
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.
EXCLUSIVE=NO
Note: This option is supported for backward compatibility only.

Use the new DIRINTEGR option.

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 FCH.
EXCLUSIVE=YES
Forces an override of the PDS(E) member processing method which allows for safe concurrent updates by other users. This option has significant performance impact. When set to YES, the member processing is performed much faster but may be affected by PDS(E) directory updates, possibly causing I/O errors if the data set is concurrently updated. This option overrides the processing method selected by Z Data Tools (EXCLUSIVE=NO, default, unless the input data set has been allocated OLD by the user), which always assumes concurrent safe processing when the data set is allocated to multiple users.
DIRINTEGR
Specifies whether to invoke a user I/O exit to process the input data set.
NO
Default. Z Data Tools 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
Z Data Tools uses safer, but slower, PDS(E) directory processing method. This method allows for safe concurrent updates of the PDS(E) directory by multiple users.
PACK
Determines if Z Data Tools 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 Z Data Tools to write the output in ISPF Packed format only if the input is in ISPF packed format.
PACK
Instructs Z Data Tools to write the output in ISPF packed format regardless of the input format.
UNPACK
Instructs Z Data Tools to write the output without ISPF packing, regardless of the input format.
NONE
Instructs Z Data Tools 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 Z Data Tools to determine if the input data set is in ISPF packed format and if so, to skip the find/change processing.

See Finding and changing data in multiple PDS members for details of the FCH commands.

Note: It is not possible to use multiple FINDNOT commands in the input stream for batch processing. Similarly, it is not possible to combine FINDNOT commands with FIND or CHANGE commands in the batch input stream.
//FMUSRFCH JOB  (@TS2,MVS6),'HFMUSER',NOTIFY=HFMUSER,
//  CLASS=A,MSGLEVEL=(1,1),MSGCLASS=H
//HFMBAT   EXEC PGM=HFMMAIN
//STEPLIB  DD  DSN=HFMUSER.FMN110.TSTLOAD,DISP=SHR
//         DD  DSN=hlq.TSTLOAD,DISP=SHR
//         DD  DSN=hlq.SHFMMOD1,DISP=SHR
//         DD  DSN=HFM.IGYV1R20.SIGYCOMP,DISP=SHR
//SYSPRINT DD SYSOUT=*
//HFMEXEC  DD DSN=HFM.EXEC,DISP=SHR
//HFMTSPRT DD SYSOUT=*
//HFMIN    DD DSN=HFMUSER.JCL.TESTING,DISP=SHR
//SYSTERM  DD SYSOUT=*
//SYSIN    DD *
$$FILEM FCH ,
$$FILEM INPUT=HFMIN,MEMBER=J*
F 'rights reserved'
C 'Copyright 2001-2002' ,
'Copyright 2001-2003' 1 71
C 'Alpha Company Ltd' ,
'Alpha Beta Company Ltd' 1 71
C 'Beta Company Ltd' ,
'Alpha Beta Company Ltd' 1 71
/+
/*