29
Fri, Nov
0 New Articles

Binary Support in CL

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

V2R2M0'S built-in %BIN function provides power worth waiting for.

It took a dozen years, but it was worth the wait. IBM has improved on CL, giving it support for binary numbers with the addition of the %BIN built-in function in V2R2M0. This new function allows you to convert two- or four-byte character strings into numeric values or, conversely, turn a numeric value into a two- or four-byte character string. For instance, command processing programs typically need to extract the number of items in a list parameter as a binary value from the first two bytes of a character variable. %BIN greatly simplifies this sort of conversion.

When I learned about binary support in CL, the first thing that crossed my mind was that the Declare (DCL) command would finally accept TYPE(*BIN) to declare binary variables. Alas, that's not the case. Your CL programs still have to accept binary parameters into character variables: TYPE(*CHAR), with a length of two or four, depending on the precision of the binary number.

Binary parameters received into character strings can also be passed along to other programs with the CALL or Transfer Control (TFR-CTL) command. Before V2R2M0, however, the CL program itself could not read the numeric value of these parameters-unless you used utility commands such as Convert Binary to Decimal (CVTBINDEC) from QUSRTOOL. I have a feeling that these utility commands will soon become obsolete.

Here's an example of using %BIN. The Change Library List (CHGLIBL) command has a parameter called LIBL, which is a simple list where you can enter from 0 to 25 library names. When you run CHGLIBL, the command passes the list of names to the command processing program (CPP) as one continuous string, prefixed with a two-byte binary counter that indicates how many values the user keyed in. This means that the CPP must receive the LIBL parameter into a 252-byte character variable (that's the two-byte prefix plus 25 times 10).

If the CPP were to be written in CL (which it isn't) and you were in charge of coding it (which you aren't), the first thing you'd have to do is determine how many names the user entered. Since CL could not process binary numbers before V2R2M0, you have to use QUSRTOOL's CVTBINDEC command or some similar technique.

The new %BIN function makes it much easier. You'd simply code:

 PGM PARM(&LIBL &CURLIB) DCL VAR(&COUNT) TYPE(*DEC) + LEN(2 0) DCL VAR(&LIBL) TYPE(*CHAR) + LEN(252) DCL VAR(&CURLIB) TYPE(*CHAR) + LEN(10) CHGVAR VAR(&COUNT) + VALUE(%BIN(&LIBL 1 2)) 

Notice the similarity between %BIN and %SST. %BIN(&LIBL 1 2) literally means: extract the first two bytes of &LIBL and convert them to a numeric value, interpreting the two bytes as a binary number.

The %BIN function needs a character variable name in parameter 1, a starting position in parameter 2, and a length in parameter 3. Like in %SST, parameters 2 and 3 can be variables instead of literals, and must yield a valid ending position when added together.

%BIN can do the opposite too, again like %SST. You can code the %BIN function in the VAR parameter of the Change Variable (CHGVAR) command. This allows you to build a character string from its numeric representation-similar to the X2C function in REXX. For example, the letter A is hexadecimal C1, which is 193 decimal. Now consider the following piece of code:

 DCL VAR(&CHARS) TYPE(*CHAR) LEN(2) CHGVAR VAR(%BIN(&CHARS 1 2)) + VALUE(193) 

This CHGVAR command has the following meaning: change the first two bytes of &CHARS to the two characters that, when taken as a binary value, are equivalent to the number 193. When the CHGVAR command runs, &CHARS changes to hexadecimal value 00C1, which is a null character followed by a letter A. The accompanying sidebar shows how you can use %BIN in a CL program to convert lowercase to uppercase characters.

In the last example, we could have coded the CHGVAR command as follows:

 CHGVAR VAR(%BIN(&CHARS)) + VALUE(193) 

In general, you can omit parameters 2 and 3 of the %BIN function when you want to start at position 1 and want to continue for the full length of the variable coded in parameter 1. Since &CHARS is two bytes long, %BIN(&CHARS 1 2) and %BIN(&CHARS) have the same meaning.

A few other rules:

%BIN can also be spelled %BINARY. This is analogous to %SST and %SUBSTRING. Once you get used to %SST, you don't want to use %SUBSTRING. It wouldn't surprise me if no one would ever want to use %BINARY for the same reason; %BIN is more convenient.

Parameter 3 of %BIN can be either 2 or 4. It cannot have any other value, although it can be omitted. If omitted, the variable coded in parameter 1 must have a length of 2 or 4.

Parameters 2 and 3 can be both indicated or both omitted. However, you cannot indicate one and omit the other. This is another way of saying that %BIN better have either one or three parameters, but never two.

You can use %BIN in the IF command's COND parameter. For instance, you can code a condition such as:

COND(&COUNT *EQ %BIN(&LIST 1 2))

Parameter 1 of the %BIN function does not accept constants-only variables. That is, %BIN(X'52E0') is not acceptable, but %BIN(&X) is.

Command parameters that expect numeric values can accept a %BIN function. For example, these two commands are both valid:

 CHGJOB RUNPTY(%BIN(&A 1 2)) CRTPF FILE(X) + RCDLEN (%BIN(&B 1 4)) 

%BIN and %SST cannot be embedded. For instance, this is invalid:

%SST(&A %BIN(&C 1 2) 4)

%BIN cannot appear in an expression whose value is destined to be passed to another program. This means that the following is invalid:

CALL PGM(X) PARM(%BIN(&D 1 2))

Is %BIN useful and important? To answer this question, you need to find out how often you'd use it. I create commands for everything, and commands always use binary prefixes in lists. I know that I'll quickly dump CVTBINDEC and embrace %BIN. Also, since DDS now supports variable-length character data, it's possible for an RPG/400 program to end up returning such a string to a CL program. The CL program can now determine the length of the string with the %BIN function so it can extract the valid portion with the %SST function:

 CALL PGM(RPGPGM) PARM(&VARLEN) CHGVAR VAR(&LEN) + VALUE(%BIN(&VARLEN 1 2)) CHGVAR VAR(&VALID) + VALUE(%SST(&VARLEN 3 &LEN)) 

This portion of code interprets the first two bytes of &VARLEN as the length of the string, then uses %SST to extract from &VARLEN the valid portion (which begins on the third byte and has a length of &LEN).

Now I want floating point variable support, being able to read multiple files, structured programming features such as iterative DO, DO WHILE, DO UNTIL, DO FOREVER, CASE, subroutines, pointers...I can dream, can't I?

Using %BIN for Case Conversion

For illustration purposes only, allow me to introduce the Convert to Uppercase (CVT-UPC) command (A1). It takes a character string of any length (up to 3000 characters) and returns another string, converted to uppercase in a 3000-byte character variable. This command can only be used in CL or REXX programs.

For illustration purposes only, allow me to introduce the Convert to Uppercase (CVT-UPC) command (Figure A1). It takes a character string of any length (up to 3000 characters) and returns another string, converted to uppercase in a 3000-byte character variable. This command can only be used in CL or REXX programs.

Parameter STRING accepts its input as a varying-length string, as indicated by VARY(*YES). The command processor automatically places a two-byte binary prefix that indicates how long the string you have entered into the parameter is.

As seen in A2, program UPC001CL receives the STRING parameter into a 3002-character variable-two bytes for the binary prefix, plus the 3000 characters the string can have as its maximum. The program then initializes &RTN-STRING to blanks and converts the length to decimal using %BIN. If this length is zero, the program ends because it means that the user didn't supply any input.

As seen in Figure A2, program UPC001CL receives the STRING parameter into a 3002-character variable-two bytes for the binary prefix, plus the 3000 characters the string can have as its maximum. The program then initializes &RTN-STRING to blanks and converts the length to decimal using %BIN. If this length is zero, the program ends because it means that the user didn't supply any input.

The loop that follows processes one character at a time, performing the conversion only if the current character is a lowercase letter. To execute the conversion, it creates &PADCHAR equal to a null (hexadecimal 00) and the current character. This is then turned into a binary number with %BIN, to which we add 64. For instance, 'a' is the 129th character in the EBCDIC set; by adding 64 we obtain 193, and 'A' is the 193rd character of the EBCDIC set.

After adding 64, we assign this value to %BIN(&PADCHAR), meaning that &PADCHAR will turn into the character representation of the numeric result. All that's left to do is move the second character of &PADCHAR into the return string's current character, and continue the loop until the current character number (&N) exceeds the length of the original string (&LENGTH).

Earlier I said that this is an example for illustration purposes only. You could have performed the same conversion by calling QDC-XLATE, using the translation table QSYSTRNTBL. Or you could have used an RPG/400 program as the command processing program, instead of CL, using the XLATE opcode. But I hope this example has shown you the enormous power of the %BIN function.


Binary Support in CL

Figure A1 Command CVTUPC

 CVTUPC: CMD PROMPT('Convert to Uppercase') PARM KWD(STRING) TYPE(*CHAR) LEN(3000) EXPR(*YES) + VARY(*YES) PROMPT('Character string') PARM KWD(RTNSTRING) TYPE(*CHAR) LEN(3000) + RTNVAL(*YES) PROMPT('Returned string (3000)') 
Binary Support in CL

Figure A2 CL program UPC001CL

 UPC001CL: + PGM PARM(&STRING &RTNSTRING) DCL VAR(&STRING) TYPE(*CHAR) LEN(3002) DCL VAR(&LENGTH) TYPE(*DEC) LEN(4 0) DCL VAR(&RTNSTRING) TYPE(*CHAR) LEN(3000) DCL VAR(&OFFSET) TYPE(*DEC) LEN(4 0) DCL VAR(&N) TYPE(*DEC) LEN(4 0) DCL VAR(&CHAR) TYPE(*CHAR) LEN(1) DCL VAR(&PADCHAR) TYPE(*CHAR) LEN(2) CHGVAR VAR(&RTNSTRING) VALUE(' ') CHGVAR VAR(&LENGTH) VALUE(%BIN(&STRING 1 2)) IF COND(&LENGTH *EQ 0) THEN(RETURN) CHGVAR VAR(&OFFSET) VALUE(3) CHGVAR VAR(&N) VALUE(1) LOOP: + CHGVAR VAR(&CHAR) VALUE(%SST(&STRING &OFFSET 1)) IF COND(&CHAR *GE 'a' *AND &CHAR *LE 'i' *OR &CHAR *GE 'j' *AND + &CHAR *LE 'r' *OR &CHAR *GE 's' *AND &CHAR *LE 'z') THEN(DO) CHGVAR VAR(&PADCHAR) VALUE(X'0000') CHGVAR VAR(%SST(&PADCHAR 2 1)) VALUE(&CHAR) CHGVAR VAR(%BIN(&PADCHAR)) VALUE(%BIN(&PADCHAR) + 64) CHGVAR VAR(%SST(&RTNSTRING &N 1)) VALUE(%SST(&PADCHAR 2 1)) ENDDO ELSE CMD(DO) CHGVAR VAR(%SST(&RTNSTRING &N 1)) VALUE(&CHAR) ENDDO CHGVAR VAR(&OFFSET) VALUE(&OFFSET + 1) CHGVAR VAR(&N) VALUE(&N + 1) IF COND(&N *LE &LENGTH) THEN(GOTO CMDLBL(LOOP)) ENDPGM 
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: