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), any CHANGE command is performed as if MEMORY=YES is specified.

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 unless MEMORY=YES is specified, and the change does not exceed the maximum variable record length for a data set.

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. 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
TRS: Locate data within a tape file

Figure 1. Syntax

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.

MEMLIST

Allows you to specify a list of member names.

member_n: The names of the members to be processed in the format (member1,member2,...member_n). Generic name masks are allowed. For example, member names can be specified as follows: (MEMLIST=ABC,DEF,HIJ*).

XMEMBERS

Provides a way to exclude from processing library members that would otherwise be selected using the MEMSTART, MEMEND, MEMBER, and MEMLIST 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'.

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').

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 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.

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, File Manager 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 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.

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 File Manager 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 File Manager (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. 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.

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 find/change processing.

MEMORY

Specifies whether to perform changes in memory.

NO

Default.

YES

Perform the changes in memory. The following occurs:

Opens the data set or member for input and reads all the records into memory.
Supports record length changes when the search and replace strings are different lengths and the resultant length is less than or equal to the maximum logical record length of a variable length data set.
Opens for output and writes all the records loaded back to the data set when a change is made.

Note:

This option is ignored for VSAM files.
This option can be used to avoid the restrictions associated with opening the data set in UPDATE mode.
The function is terminated if there is insufficient memory to load the entire member or data set into memory. A larger region size may be required.
For compressed data sets, the change is always performed in memory.
Memory processing performs slower than update in place.

CHGISPF=NO|YES

Default is NO. Specify CHGISPF=YES to mimic the ISPF Editor CHANGE command behavior which preserves positional relationships when the "to" and "from" strings have different lengths by absorbing or inserting blank characters as required. For example, if a long string is changed to a shorter string, the shorter string is padded with blanks to maintain column position of any data to the right of the change.

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),'FMNUSER',NOTIFY=FMNUSER,
//  CLASS=A,MSGLEVEL=(1,1),MSGCLASS=H
//FMNBAT   EXEC PGM=FILEMGR
//STEPLIB  DD  DSN=FMNUSER.FMN110.TSTLOAD,DISP=SHR
//         DD  DSN=hlq.TSTLOAD,DISP=SHR
//         DD  DSN=hlq.SFMNMOD1,DISP=SHR
//         DD  DSN=FMN.IGYV1R20.SIGYCOMP,DISP=SHR
//SYSPRINT DD SYSOUT=*
//FMNEXEC  DD DSN=FMN.EXEC,DISP=SHR
//FMNTSPRT DD SYSOUT=*
//DDIN     DD DSN=FMNUSER.JCL.TESTING,DISP=SHR
//SYSTERM  DD SYSOUT=*
//SYSIN    DD *
$$FILEM FCH ,
$$FILEM INPUT=DDIN,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
/+
/*