(Editor's note: Bob is on vacation this week, so he offers this "best of" article in case you missed it the first time.)
I've decided to give you a little gift. This issue includes a full-functioning procedure that performs a certain task and returns a value to the caller. The function that is performed is one that I've needed frequently in RPG, so I decided to write it myself rather than wait for the compiler to do it.
In my experience writing C++ applications for Windows and Linux, I've had the need for a Find/Replace function time and time again. In the world of OS/400 and RPG, I've needed one very frequently in some of the tools that I use. Sure, there are plenty of "Find" functions in OS/400, but there are few "Replace" functions-or more appropriately, few "Find and Replace" functions.
When the year 2000 was a future problem, one of my consulting clients was paying developers to sit at their desks and modify existing applications by changing the names of fields in over 1,500 source members. The developers had gone through nearly 78 programs over a three-week period when I was brought into the picture.
The client asked me to help with the conversion. Of course, dollar signs popped into my head, but I told him that he might be better off using a tool to do this kind of work. At the time, we knew of no such tool, so I gave him a quote to write it for him. He agreed, and I delivered a command that not only sought out the old field names, but also replaced the old names with the new names and was sensitive to RPG's columnar nature. Yes, the new field names were longer than the original field names.
Today, there is more of a need for a Find/Replace procedure than there is for a full-scale source scan and replace command. I've often needed to search for a pattern in a character field and replace it with something else; whether it is doubling up quotes, removing dashes, or simply changing portions of a street address. A Find/Replace procedure is very important in my day-to-day programming activities.
RPG IV already does a very good job of using the SCAN opcodes or %SCAN built-in function. It also does a good job of replacing data using either %SUBST or the %REPLACE built-in functions. So, to do a simple one-time Find/Replace, all an RPG IV programmer needs to do is something like this:
.....CSRn01..............OpCode(ex)Extended-factor2+++++++++++++++++++++++++++
0001 C eval nPos = %scan(szFindText : szData)
0002 C if nPos > 0
0003 C eval szData = %replace(szReplaceText : szData :
0004 C nPos : nReplaceLen)
0005 C endif
The %scan built-in function on Line 1 searches the field named szData for the search pattern. The search pattern is stored in the field named szFindText. If %scan finds a match, the position within szData is returned and stored in the field named nPos. %SCAN is a case-sensitive scan; upper- and lowercase letters are taken into account so that, for example, an uppercase M does not match a lowercase m.
If a match is detected, nPos will be greater than zero (Line 2). Then, on Line 3, the %Replace built-in function is called to replace the original text with the new text. The field named szReplaceText (parameter 1) contains the replacement text--that is, it contains the text that will be inserted into the szData field (parameter 2). The szReplaceText is inserted into szData beginning in the positions identified by the nPos field (parameter 3). The fourth parameter of the %Replace built-in function (nReplaceLen) can be confusing. It identifies the number of characters in szData that will be deleted from the szData field--starting with the position specified in the nPos field--before the szReplaceText is inserted. If this parameter is not specified, then the length of the szReplaceText parameter is used.
Caveat Emptor: %Scan is case-sensitive only. You'd have to write your own "ignore case" procedures and convert the database before the scan is performed if you need that kind of functionality.
The fourth parameter of %Replace is optional, and, if
unspecified, it defaults to the field length of the first parameter. This is
important because the field length is not always the length you want. Often the
desired length is the length of the text in the field. So something like
%Len(%TrimR(szReplaceText)) may be required.
You can delete text from the target field (szData in the example) by using a variable-length field for the szReplaceText, setting its length to zero, and then specifying a replacement length.
In the following example, a field is searched for a string of text, and then that text is deleted from the original field.
0001 C eval nPos = %scan(ToLower(%TrimR(szFindText))
0002 C : ToLower(szData) )
0003 C if nPos > 0
0004 C eval szReplaceText = ''
0005 C eval nReplaceLen = %Len(%TrimR(szFindText))
* // Delete some text from the szData field
0007 C eval szData = %replace('' : szData :
0008 C nPos : nReplaceLen)
0009 C endif
By inserting an empty string--via double apostrophes ('')--into the szData field at the position where the text was found, no new text replaces the old, and the original text is deleted.
A Better Way to Search and Destroy
I used variations of this type of technique many times and decided it was time to write a nicely packaged Find and Replace procedure. Of course, I would prefer a %FindReplace built-in function in the RPG IV language, but that is still years away. Listed in Figure 1 is the RPG IV source code for a module named FINDREPL that contains several procedures. The primary procedure is named FindReplace, and along with it are CvtCase (convert between upper/lowercase), ToLower (convert to lowercase), and ToUpper (convert to uppercase).
There are also three include members (aka /COPY's) that are used by the source listed in Figure 1. All three of these source members should be stored in the QCPYSRC source file. The source member FindRepl contains the procedure prototype for the FindReplace procedure, the source member APIErrEx contains two data structure formats used by OS/400 APIs, and the source member GetOpDesc contains the prototype for the ILE CEEDOD procedure. These source members are listed in Figures 2, 3, and 4 respectively.
Find/Replace Parameters
The FindReplace procedure accepts five parameters, but only the first three are required. The following is a brief description of each parameter. See the source code for more details.
|
Parameter
|
Usage
|
Description
|
|
szFind
|
Input
|
The Find Text-This is the text that will be searched for in the field
specified for the third parameter. This field may be up to 2048 positions in
length. It is a varying-length field and CONST, so fields that are fixed or
varying-length may be specified with lengths up to 2048 positions.
|
|
szReplace
|
Input
|
The Replacement Text-his is the text that will replaced the "Find text"
(parameter 1) in the field specified for the third parameter. This field may be
up to 2048 positions in length. It is a varying-length field and CONST, so
fields that are fixed or varying-length may be specified with lengths of up to
2048 positions. If this parameter is a varying-length field and it is empty
(i.e., its length is equal to zero), then the find text is deleted from the
search field (third parameter).
|
|
szData
|
Input
|
The Search Field-This parameter identifies the text that will be searched
for the value specified in the find text (first parameter).
|
|
bOptions
|
Optional
Input |
Options-This parameter controls the search-and-replace action. Currently,
only two options are supported.
FR_MATCHCASE-Performs a case-sensitive find/replace. Unless this is specified, a case-insensitive find is performed. FR_FINDFIRST-Locate and replace the first occurrence of the Find text. By default, all occurrences are located and replaced. This parameter uses bit patterns to detect the options settings. There are compiler directives in the code that control whether it is being compiled under OS/400 V5R2 (where bit-wise operators are built-in). If not under V5R2 or later, then "grunt" methods are used to check the bit mask. |
|
nCount
|
Optional
Output |
Replace Count-This field, if specified, is set to the number of
occurrences of the find/replace text. It must be a 4-byte integer field. These
types of fields are normally defined as 10i0 fields.
|
The Find/Replace procedure source compiles into a module object. The module may be bound into your programs by copy (as the module itself) or by reference (stored in a service program). To store it in a service program, use the CRTSRVPGM command after the CRTRPGMOD command.
Compiling the Find/Replace Procedure
To compile the source, just use the regular option 15 in PDM or set up your compiler setting in CodeStudio to run the following command:
To create a service program with just this module and procedure in it, run the following command:
This command assumes TOOLS is the name of the library where you've stored the module object.
Summary
The Find/Replace procedure is only as fast as the corresponding %SCAN and %REPLACE built-in functions. So it should perform about as fast as anything you can write on your own.
So use it and enjoy it!
|
Figure 1: FindReplace and supporting procedures' source
|
Figure 2: FindReplace, ToUpper, ToLower, and CvtCase
Prototypes
|
Figure 3: API Error Data Structure
|
Figure 4: Get Operational Descriptor (CEEDOD) Prototype
Bob Cozzi is author of the best-selling The Modern RPG IV Language, Fourth Edition as well as RPG TNT: 101 Dynamite Tips 'n Techniques with RPG IV and is host of the i5 Podcast Network, which provides free video and audio podcasts to the i5 community. You can also see him in person at RPG World in May 2007.
Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.
MC Press books written by Robert Cozzi available now on the MC Press Bookstore.
 |
||
 |
|
RPG TnT Get this jam-packed resource of quick, easy-to-implement RPG tips! List Price $65.00 Now On Sale
|
|
||
 |
|
The Modern RPG IV Language Cozzi on everything RPG! What more could you want? List Price $99.95
Now On Sale
|
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online