05
Tue, Nov
7 New Articles

Working with Strings in CL Programs

CL
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Can you imagine an electronics technician who can't solder? Would you want to eat the cooking of a chef who never uses a measuring cup? Would you hire a plumber who uses only a monkey wrench, no matter what the problem is?

You expect better of professionals. You expect them to have good tools and know how to use them.

We should expect no less of ourselves. Being professional programmers, we should have a thorough understanding of all aspects of CL, including how to effectively work with character strings.

CL is a control language used as the primary interface to OS/400, not an application programming language, so it doesn't provide the rich set of string-handling functions and operators you'll find in other languages. Nevertheless, CL's string capabilities are well-suited for the type of work it has to do.

Read on; you may discover that there's more to handling strings in CL than you thought.

CL provides a tool for working with parts of strings. A built-in function written as either %SUBSTRING or %SST, it operates on a character string contained in a CL character variable or in a local data area. The result of the %SST function is a subset of an existing character string. %SST has three parameters-a CL variable name or the special value *LDA, a starting position, and length. The starting position and length may be CL variables or literals.

%SST can be used in any CL command parameter that permits expressions. It is probably most commonly used in the Change Variable (CHGVAR) command, where both the VALUE and the VAR parameters permit expressions. In the VALUE parameter, %SST extracts a portion of a string. In the VAR parameter, it modifies a portion of a string.

1 contains excerpts from a CL program that uses the substring function. Some information about an imaginary factory is stored in a data area called INFO. The program starts by retrieving information from the data area into the &PLANT_INFO variable. The program uses portions of the data in &PLANT_INFO to display the plant name and location on a prompt screen.

Figure 1 contains excerpts from a CL program that uses the substring function. Some information about an imaginary factory is stored in a data area called INFO. The program starts by retrieving information from the data area into the &PLANT_INFO variable. The program uses portions of the data in &PLANT_INFO to display the plant name and location on a prompt screen.

After loading the &PLANT_INFO variable, the program uses the CHGVAR command to copy 20 characters-starting in position 5 of the plant data-into the variable &PLNAME. The program then uses a second CHGVAR command to load the &PLCITY variable from bytes 41 through 58 of the plant data.

Don't fall into the trap of thinking that you can only use %SST in the CHGVAR command. The job in 1 includes some programs that run only for assembly plants. The IF statement checks positions 96 through 98 of the information extracted from the data area to determine whether the factory running the job is an assembly plant. Using %SST, there's no need to copy those three bytes into a separate CL variable and test that CL variable in the IF command.

Don't fall into the trap of thinking that you can only use %SST in the CHGVAR command. The job in Figure 1 includes some programs that run only for assembly plants. The IF statement checks positions 96 through 98 of the information extracted from the data area to determine whether the factory running the job is an assembly plant. Using %SST, there's no need to copy those three bytes into a separate CL variable and test that CL variable in the IF command.

2 illustrates how to change part of a CL variable using the CHGVAR command and %SST. This job runs an Open Query File (OPNQRYF) command, which selects records for a certain type of company. You enter a valid company type code, and the program inserts it in positions 8 and 9 of the record selection string (for example, if you enter 83, &QRYSLT becomes 'COTYPE=83').

Figure 2 illustrates how to change part of a CL variable using the CHGVAR command and %SST. This job runs an Open Query File (OPNQRYF) command, which selects records for a certain type of company. You enter a valid company type code, and the program inserts it in positions 8 and 9 of the record selection string (for example, if you enter 83, &QRYSLT becomes 'COTYPE=83').

CL also has tools that combine two strings to form new strings. The three CL concatenation operators-*CAT, *TCAT, and *BCAT-differ in how they treat the first string.

There are two forms for each operator: a predefined special value beginning with the * character (e.g., *CAT) and a symbol (e.g., ||). Although the symbols may be slightly easier to key, I think it's better for readability to use the special values.

The *CAT (or ||) operator appends one string to the end of another. The new string contains all the characters of the first string followed by all the characters of the second one.

The *TCAT (or |<) operator trims trailing blanks from the first string before appending the second string.

The *BCAT (or |>) operator trims trailing blanks from the first string, appends one blank, and adds the second string.

3 gives some examples of how these operators combine data.

Figure 3 gives some examples of how these operators combine data.

Concatenation operators cannot be used with decimal values. If you want to concatenate a decimal value, you'll have to copy it to a character variable first and then concatenate the character variable.

CL also has access to string-handling tools that are not part of the CL language, such as the OS/400 APIs that work with strings. You can call these APIs from programs written in any AS/400 language, but since most high-level languages (HLLs) have their own string-handling functions, operators, and commands, you'll probably find them most useful for CL programming.

The QCLSCAN program looks for the occurrence of one string within another string. It may look a little scary because it has nine parameters, but it's really very easy to use.

4 illustrates how you might use QCLSCAN. Assume the program has read the value DOPF/DOOREP from a file and placed it into variable &INSTRING. To find the position of the slash, you put a single slash, left-justified, into &PATTERN and call QCLSCAN. After QCLSCAN, the value of &RTNCODE is 5, because the slash is in the fifth position of &INSTRING. If there were no slash in &INSTRING, &RTNCODE would be 0.

Figure 4 illustrates how you might use QCLSCAN. Assume the program has read the value DOPF/DOOREP from a file and placed it into variable &INSTRING. To find the position of the slash, you put a single slash, left-justified, into &PATTERN and call QCLSCAN. After QCLSCAN, the value of &RTNCODE is 5, because the slash is in the fifth position of &INSTRING. If there were no slash in &INSTRING, &RTNCODE would be 0.

Another useful program is QDCXLATE, which uses a translation table to alter a string. In its simplest form, QDCXLATE has three parameters-the string to be translated, the length of the string, and the name of the translation table to use. There are seven more parameters, but they are optional. A common use of this program is to capitalize lowercase letters. You can see an example program fragment using QDCXLATE in 5.

Another useful program is QDCXLATE, which uses a translation table to alter a string. In its simplest form, QDCXLATE has three parameters-the string to be translated, the length of the string, and the name of the translation table to use. There are seven more parameters, but they are optional. A common use of this program is to capitalize lowercase letters. You can see an example program fragment using QDCXLATE in Figure 5.

You can also use the QLGCNVCS Original Program Model (OPM) and QlgConvertCase Integrated Language Environment (ILE) APIs to carry out case conversion. You may find them more suitable for your needs, as they work from a coded character set ID (CCSID) rather than a translation table. CCSIDs are designed for the natural languages people speak, while a translation table merely converts data based on hexadecimal value.

I've presented these APIs only briefly. Read more about them in the AS/400 System API Reference manual.

If you are disappointed that CL doesn't offer other string-handling tools you need, relax. You can write your own programs to add functions to CL.

I can illustrate this capability with an idiosyncrasy of mine: I dislike leading zeros. Messages like "There were 00320 matches" bother me. CL doesn't have a function to remove leading zeros, so I wrote a program I call TRIMLDCHAR (shown in 6) that will trim any leading character from a string.

I can illustrate this capability with an idiosyncrasy of mine: I dislike leading zeros. Messages like "There were 00320 matches" bother me. CL doesn't have a function to remove leading zeros, so I wrote a program I call TRIMLDCHAR (shown in Figure 6) that will trim any leading character from a string.

My program requires four pieces of information-the untrimmed string, the leading character to remove (usually a zero or a blank), the trimmed string, and a flag called SETLR. If the character in the second parameter is not the leading character in the input string, the trimmed string is identical to the input string. I give SETLR some value other than 1 on all but the last call to TRIMLDCHAR, so the program remains active in my job. I deactivate TRIMLDCHAR on the last call by passing the value 1 through the SETLR parameter.

7 shows how to use the program to remove leading zeros from a CL variable. &MATCH_CT contains the number of hits from a search routine. The first CHGVAR command copies the decimal value into character value &MATCH_A because decimal values can't be used with concatenation operators. Program TRIMLDCHAR copies the value in &MATCH_A, without leading zeros, into &MATCH_B. Finally, the last CHGVAR builds the message text. Now, the message reads "There were 320 matches," which is more to my liking.

Figure 7 shows how to use the program to remove leading zeros from a CL variable. &MATCH_CT contains the number of hits from a search routine. The first CHGVAR command copies the decimal value into character value &MATCH_A because decimal values can't be used with concatenation operators. Program TRIMLDCHAR copies the value in &MATCH_A, without leading zeros, into &MATCH_B. Finally, the last CHGVAR builds the message text. Now, the message reads "There were 320 matches," which is more to my liking.

By adding this program to my toolbox, I have extended the CL language. I can call this utility from a CL program whenever I need to remove leading blanks, leading zeros, or some other leading character from a string. Of course, I can also call this utility from programs written in other languages, so I have extended the string-handling capabilities of the other AS/400 programming languages as well.

Since you can write utility programs, the ability of your CL programs to work with strings is limited only by your imagination.

By the way, this example uses the OPM model. If you're using ILE, you might want to consider converting it to an ILE RPG program.

Often, the only characteristic that distinguishes the professional from the amateur is the professional's greater skill with the tools of the trade. Be the best CL programmer you can be. Master CL's existing string-handling tools, and invent other tools as you need them.

Ted Holt is an associate technical editor for Midrange Computing.He can be reached by E-mail at This email address is being protected from spambots. You need JavaScript enabled to view it..

REFERENCES

AS/400 CL Programming (SC41-3721, CD-ROM QBKAUO00).

AS/400 CL Reference (SC41-3722, CD-ROM QBKAUP00).

AS/400 System API Reference (SC41-3801, CD-ROM QBKAVD00).


Working with Strings in CL Programs

Figure 1: Retrieving Substrings with the %SST Function

 DCL VAR(&PLANT_INFO) TYPE(*CHAR) LEN(128) DCLF FILE(MYDSPF) ... RTVDTAARA DTAARA(INFO) RTNVAR(&PLANT_INFO) /* Variables &PLNAME and &PLCITY are defined in the display file */ CHGVAR VAR(&PLNAME) VALUE(%SST(&PLANT_INFO 5 20)) CHGVAR VAR(&PLCITY) VALUE(%SST(&PLANT_INFO 41 18)) SNDRCVF /* Prompt with display file */ ... /* processing for all types of plants */ CALL PGM1 CALL PGM2 /* processing for assembly plants only */ IF COND(%SST(&PLANT_INFO 96 3) *EQ 'ASM') THEN(DO) CALL PGM3 CALL PGM4 ENDDO 
Working with Strings in CL Programs

Figure 2: Changing a Substring with the %SST Function

 DCL VAR(&QRYSLT) TYPE(*CHAR) VALUE('COTYPE=XX') DCL VAR(&SELCODE) TYPE(*DEC) LEN(2 0) /* &SELCODE was entered by the user */ /* Insert it into the query selection expression */ CHGVAR VAR(%SST(&QRYSLT 8 2)) VALUE(&SELCODE) OPNQRYF ... QRYSLT(&QRYSLT) 
Working with Strings in CL Programs

Figure 3: Comparison of CL Concatenation Operators



Working with Strings in CL Programs

Figure 4: Example Using QCLSCAN

 DCL &INSTRING *CHAR 512 /* String to search */ DCL &INLENGTH *DEC 3 VALUE(512) /* Length of string to search */ DCL &BEGPOS *DEC 3 VALUE( 1) /* Start searching at position */ DCL &PATTERN *CHAR 10 /* String to search for */ DCL &PATLEN *DEC 3 VALUE( 10) /* Length of search string */ DCL &XLATE *CHAR 1 VALUE('1') /* translate to uppercase */ DCL &TRIM *CHAR 1 VALUE('1') /*ignore trailing blanks in &PATTERN */ DCL &WILDCARD *CHAR 1 VALUE(' ') /* no wildcards in &PATTERN */ DCL &RTNCODE *DEC 3 /* position found or error code */ ... CALL QCLSCAN PARM(&INSTRING &INLENGTH &BEGPOS &PATTERN + &PATLEN &XLATE &TRIM &WILDCARD &RTNCODE) 
Working with Strings in CL Programs

Figure 5: Capitalizing with QDCXLATE

 DCL &INSTR *CHAR 75 /* String to translate */ DCL &INLEN *DEC 5 VALUE(75) /* Length of &INSTR */ DCL &TABLE *CHAR 10 VALUE('QSYSTRNTBL') /* Translation table name */ ... CALL PGM(QDCXLATE) PARM(&INLEN &INSTR &TABLE) 
Working with Strings in CL Programs

Figure 6: Program TRIMLDCHAR

 * Strip a leading character from a string * * Parameters: * IN - the string to be edited * LDCHAR - the leading character to be stripped * OUT - the edited string * SETLR - if "1", turn on the LR indicator * * If the input string contains only the character to be stripped, * this program places one character, left-adjusted, into the * output string. * *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 C *ENTRY PLIST C PARM IN 32 C PARM LDCHAR 1 C PARM OUT 32 C PARM SETLR 1 * C LDCHAR CHECKIN PX 30 C PX IFGT *ZERO C SUBSTIN:PX OUT P C ELSE C MOVELLDCHAR OUT P C ENDIF * C SETLR IFEQ '1' C MOVE *ON *INLR C ENDIF * C RETRN *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 
Working with Strings in CL Programs

Figure 7: Trimming Leading Zeros

 DCL VAR(&MATCH_CT) TYPE(*DEC) LEN(5) DCL VAR(&MATCH_A) TYPE(*CHAR) LEN(32) DCL VAR(&MATCH_B) TYPE(*CHAR) LEN(32) DCL VAR(&MSG) TYPE(*CHAR) LEN(80) ... CHGVAR VAR(&MATCH_A) VALUE(&MATCH_CT) CALL PGM(TRIMLDCHAR) PARM(&MATCH_A '0' &MATCH_B '1') CHGVAR VAR(&MSG) VALUE('There were' *bcat &MATCH_B *bcat + 'matches.') ... 
TED HOLT

Ted Holt is IT manager of Manufacturing Systems Development for Day-Brite Capri Omega, a manufacturer of lighting fixtures in Tupelo, Mississippi. He has worked in the information processing industry since 1981 and is the author or co-author of seven books. 


MC Press books written by Ted Holt available now on the MC Press Bookstore.

Complete CL: Fifth Edition Complete CL: Fifth Edition
Become a CL guru and fully leverage the abilities of your system.
List Price $79.95

Now On Sale

Complete CL: Sixth Edition Complete CL: Sixth Edition
Now fully updated! Get the master guide to Control Language programming.
List Price $79.95

Now On Sale

IBM i5/iSeries Primer IBM i5/iSeries Primer
Check out the ultimate resource and “must-have” guide for every professional working with the i5/iSeries.
List Price $99.95

Now On Sale

Qshell for iSeries Qshell for iSeries
Check out this Unix-style shell and utilities command interface for OS/400.
List Price $79.95

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More 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.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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.

  • SB HelpSystems ROBOT GenericForms 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.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

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

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra 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: