The Find and Replace String (FNDRPLSXCL) command finds and replaces a string of one or more characters with a replacement string of one or more characters.

This function is also available with command FNDRPLSTR in library VC2XCL. Any use of this alternative command name should be library qualified in case the i operating system were to use this command name in a future release.

Parameters

String to find (STRING)

Specifies the character string to find within the VAR parameter.

If a CL variable is used trailing blanks in the variable are ignored. If a literal value is used trailing blanks are ignored unless a quoted literal value is specified.

This is a required parameter.

character-value

Specify the string that is to be searched for.f

Replacement string (RPLSTRING)

Specifies the character string that is to replace all occurrences of the character string specified by the STRING parameter.

If a CL variable is used trailing blanks in the variable are ignored. If a literal value is used trailing blanks are ignored unless a quoted literal value is specified.

If the character string specified is shorter in length than the STRING parameter value then blank padding will be performed on the returned VAR parameter value.

If the character string specified is longer in length than the STRING parameter value then truncation will be performed on the returned VAR parameter value. If the VARCCSID is a multibyte CCSID this truncation can cause the last character returned in the VAR variable to be a partial encoding of the character.

This is a required parameter.

character-value

Specify the replacement character string.

Variable to search and change (VAR)

Specifies the CL variable that is to be searched for the string of characters identified by the STRING parameter. Each occurrence of the STRING value will be replaced by the RPLSTRING value.

This is a required parameter.

character-value

Specify the CL variable to be searched and possibly modified.

Starting position in variable (STRPOS)

Specifies the byte position within the VAR parameter where the search is to start.

1

The search starts with the first byte of the VAR parameter.

integer

Specify the byte at which the search should start.

Ignore case (IGNCASE)

Specifies if lower case and uppercase characters should be considered as matches when searching for the character string identified by the STRING parameter within the character string identified by the VAR parameter.

*YES

Lowercase and uppercase differences are ignored. For example an uppercase 'A' in the STRING parameter will be considered a match for a lowercase 'a' in the VAR parameter.

*NO

Lowercase and uppercase characters are considered as unique characters for matching purposes.

CCSID of string (STRCCSID)

Specifies the CCSID of the character string identified by the STRING parameter.

*JOB

The character string identified by the STRING parameter is encoded using the job CCSID. If the job CCSID is 65535 the default job CCSID will be used.

*ASCII

The character string identified by the STRING parameter is encoded using CCSID 819 (ISO Latin 1).

*UCS2

The character string identified by the STRING parameter is encoded using CCSID 13488 (Unicode UCS2).

*UTF8

The character string identified by the STRING parameter is encoded using CCSID 1208 (Unicode UTF8).

*UTF16

The character string identified by the STRING parameter is encoded using CCSID 1200 (Unicode UTF16).

0-65533

Specify the CCSID of the STRING parameter data.

CCSID of replacement string (RPLCCSID)

Specifies the CCSID of the character string identified by the RPLSTRING parameter.

*JOB

The character string identified by the RPLSTRING parameter is encoded using the job CCSID. If the job CCSID is 65535 the default job CCSID will be used.

*ASCII

The character string identified by the RPLSTRING parameter is encoded using CCSID 819 (ISO Latin 1).

*UCS2

The character string identified by the RPLSTRING parameter is encoded using CCSID 13488 (Unicode UCS2).

*UTF8

The character string identified by the RPLSTRING parameter is encoded using CCSID 1208 (Unicode UTF8).

*UTF16

The character string identified by the RPLSTRING parameter is encoded using CCSID 1200 (Unicode UTF16).

0-65533

Specify the CCSID of the RPLSTRING parameter data.

CCSID of variable to search (VARCCSID)

Specifies the CCSID of the character string identified by the VAR parameter.

*JOB

The character string identified by the VAR parameter is encoded using the job CCSID. If the job CCSID is 65535 the default job CCSID will be used.

*ASCII

The character string identified by the VAR parameter is encoded using CCSID 819 (ISO Latin 1).

*UCS2

The character string identified by the VAR parameter is encoded using CCSID 13488 (Unicode UCS2).

*UTF8

The character string identified by the VAR parameter is encoded using CCSID 1208 (Unicode UTF8).

*UTF16

The character string identified by the VAR parameter is encoded using CCSID 1200 (Unicode UTF16).

0-65533

Specify the CCSID of the VAR parameter data.

Examples for FNDRPLSXCL

Example 1: Replace ABC With XYZ

Dcl        Var(&Target) Type(*Char) Len(10) +
             Value('AbcdaBCuvw')
FndRplSXCL String('abc') RplString('XYZ') Var(&Target)

This example replaces all instances of the character string abc, regardless of case, with the uppercase string XYZ. After the FNDRPLSXCL command runs the CL variable &Target has a value of 'XYZdXYZuvw'.

Example 2: Changing a Variable to All Equal Signs

Dcl        Var(&Target) Type(*Char) Len(10) +
             Value('AbcdaBCuvw')
ChgVar     Var(&Target) Value(' ')
FndRplSXCL String(' ') RplString('=') Var(&Target)

This example first sets the value of CL variable &Target to all blanks. The FNDRPLSXCL command then replaces all blanks with the equal (=) sign. After the FNDRPLSXCL command runs the CL variable &Target has a value of '=========='.

Example 3: Replacing All Instances of ? with XCL

Dcl        Var(&Target) Type(*Char) Len(10)
ChgVar     Var(&Target) Value('m?_N?vWxYz')
FndRplSXCL String('?') RplString('XCL') Var(&Target)

This example replaces all instances of the question mark ('?') with the character string 'XCL'. After the FNDRPLSXCL command runs the CL variable &Target has a value of 'mXCL_NXCLv'. Due to the expansion of the single character ? to the three characters XCL the last four bytes of the original &Target value are truncated.

Example 4: Replacing the Characters XCL with x

Dcl        Var(&Target) Type(*Char) Len(10)
ChgVar     Var(&Target) Value('A XCL abcd')
FndRplSXCL String('XCL') RplString('x') Var(&Target)

This example replaces all instances of the string XCL with the lowercase x character. After the FNDRPLSXCL command runs the CL variable &Target has a value of 'A x abcd '. Due to the replacement of the three characters XCL with the single character x the last two bytes of the original &Target value are set to blanks.

Example 5: Replacing ASCII Blanks with ASCII Equal Sign

Dcl        Var(&Target) Type(*Char) Len(10)
Dcl        Var(&ASC_String) Type(*Char) Len(10) +
             Value(X'61206220632064206520')
ChgVar     Var(&Target) Value(&ASC_String)
FndRplSXCL String(' ') RplString('=') Var(&Target) +
             VarCCSID(819)

This example replaces all ASCII blanks within the variable &Target with the equal sign. The CL variable &Target value is first set to the character string 'a b c d e ' in ASCII CCSID 819. After the FNDRPLSXCL command runs CL variable &Target has a value of 'a=b=c=d=e=' in ASCII CCSID 819. The hex value of &Target is x'613D623D633D643D653D'.

The values for STRING and RPLSTRING are encoded in the job CCSID. Only the VAR parameter is encoded in ASCII CCSID 819.

Error messages for FNDRPLSXCL

*ESCAPE Messages

XCL500B

CCSID value of &1 is not supported.

XCL500C

Encoding scheme &1 not supported.

XCL500D

Function did not complete. See previously listed messages related to possible user errors.

XCL5015

Invalid start position specified.

XCL9002

Function did not complete. See previously listed messages related to possible user errors.

XCL9003

Function did not complete. See previously listed messages for possible cause.

XCL9004

Function did not complete. See previously listed messages for possible cause.

XCL9005

Function did not complete. Contact your service provider.