While the vast majority of commercial applications do not need to be concerned with individual bit values, every once in a while you run across a support application-such as data collection or communications with another system-where the ability to test and/or set a specific bit becomes critical. Some languages, such as RPG and C, provide direct support for this type of operation. Other languages, with CL and COBOL coming quickly to mind, do not. Traditionally, I've seen some rather convoluted coding in CL and COBOL in order to work at the bit level. In this article, we'll look at a technique that greatly simplifies this type of work.
The operating system i5/OS comes standard with several languages. The standard language most developers are familiar with is Control Language (CL). Another language that is on every system however is Machine Interface (MI). And one of the beauties of the i5/OS Integrated Language Environment (ILE) is that we can embed ILE MI directly into any of the other ILE languages. In particular, there are MI instructions for a bit-wise AND with two input values that can be used for bit-level testing (ANDSTR) and a bit-wise OR with two input values that can be used for bit-level setting (ORSTR). In this article, we'll see how to use these MI instructions from ILE CL and ILE COBOL.
The first instruction, ANDSTR, is shown below and documented here:
ANDSTR(
Receiver_string :address of aggregate(*)
First_source_string :address of aggregate(*)
Second_source_string :address of aggregate(*)
String_length :unsigned binary(4,8) value which specifies the
length of the three strings
The ANDSTR instruction performs a bit-by-bit ANDing of each byte of First_source_string, for the number of bytes specified by String_length, to each corresponding byte of Second_source_string. The results of this operation are returned in Receiver_string. So if we assume a bit-numbering convention of 0 to 7, where bit 2 being on is equivalent to b'xx1xxxxx' (x meaning we don't care about the bit value), and we want to test a Data field for bit 2 being on, we could ANDSTR Data with the value x'20' (b'00100000') and know with confidence that if the returned Receiver_string is set to this same value, x'20', then bit 2 is indeed on. If we wanted to test for bits 0, 1, and 7 being on, we could AND Data with x'C1' (b'11000001'), test if Receiver_string is equal to the value x'C1' and, if so, know that bits 0, 1, and 7 are all on.
By convention, MI instructions are treated as if they were callable functions with the instruction name prefixed by an underscore. In reality, no CALL is being performed. The MI instruction is actually embedded directly into your application program.
In ILE CL, we can use ANDSTR as shown here with program TESTBIT:
Pgm Parm(&Data)
Dcl Var(&Data) Type(*Char) Len(1)
Dcl Var(&Receiver) Type(*Char) Len(1)
Dcl Var(&String_Two) Type(*Char) Len(1) +
Value(X'20')
Dcl Var(&Length) Type(*UInt) Len(4) Value(1)
CallPrc Prc('_ANDSTR') Parm((&Receiver) (&Data) +
(&String_Two) (&Length *ByVal))
If Cond(&Receiver = &String_Two) Then( +
SndPgmMsg Msg('The bit is on.') ToPgmQ(*Ext))
Else Cmd(SndPgmMsg Msg('The bit is off.') +
ToPgmQ(*Ext))
EndPgm
Calling this program with CALL TESTBIT x'20' will result in the message "The bit is on" being displayed. Entering CALL TESTBIT x'10' will result in the message "The bit is off."
Here's the same program in COBOL:
PROCESS NOMONOPRC.
IDENTIFICATION DIVISION.
PROGRAM-ID. TESTBIT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
LINKAGE TYPE SYS FOR "_ANDSTR".
DATA DIVISION.
WORKING-STORAGE SECTION.
01 String-Two PIC X(1) VALUE x"20".
01 Receiver PIC X(1).
LINKAGE SECTION.
01 Data-Field PIC X(1).
PROCEDURE DIVISION USING Data-Field.
MAIN-LINE.
CALL "_ANDSTR" USING BY REFERENCE Receiver,
BY REFERENCE Data-Field,
BY REFERENCE String-Two,
BY VALUE LENGTH OF Data-Field.
IF Receiver EQUAL String-Two DISPLAY "The bit is on."
ELSE DISPLAY "The bit off.".
STOP RUN.
The second instruction, ORSTR, is shown below and documented here.
ORSTR(
Receiver_string :address of aggregate(*)
First_source_string :address of aggregate(*)
Second_source_string :address of aggregate(*)
String_length :unsigned binary(4,8) value
which specifies the length of the
three strings
)
This instruction performs a bit-by-bit ORing of each byte of First_source_string, for the number of bytes specified by String_length, to each corresponding byte of Second_source_string. The results of this operation are returned in Receiver_string. So if we want to unconditionally set bit 3 of Data to on, we could ORSTR Data with the hex value x'10'. This will force bit 3 to on while leaving all other bits of Data in their current state. To set bits 1, 2, and 7, we would ORSTR with x'C1'.
In ILE CL, we can use ORSTR as shown here with program SETBIT:
Pgm Parm(&Data)
Dcl Var(&Data) Type(*Char) Len(1)
Dcl Var(&Receiver) Type(*Char) Len(1)
Dcl Var(&String_Two) Type(*Char) Len(1) +
Value(X'10')
Dcl Var(&Length) Type(*UInt) Len(4) Value(1)
CallPrc Prc('_ORSTR') Parm((&Receiver) (&Data) +
(&String_Two) (&Length *ByVal))
SndPgmMsg Msg(&Receiver)
EndPgm
Calling this program with CALL SETBIT 'C' will result in the message "L" as the character 'C' in EBCDIC is x'C3' (b'11000011'), and by setting bit 3, we have changed &Receiver to x'D3' (b'11010011')-the letter 'L' in EBCDIC. Using CALL SETBIT 'L' will result in the message "L" as bit 3 is already on. So &Receiver retains the same value as &Data.
Here's the same program in COBOL:
PROCESS NOMONOPRC.
IDENTIFICATION DIVISION.
PROGRAM-ID. SETBIT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
LINKAGE TYPE SYS FOR "_ORSTR".
DATA DIVISION.
WORKING-STORAGE SECTION.
01 String-Two PIC X(1) VALUE x"10".
01 Receiver PIC X(1).
LINKAGE SECTION.
01 Data-Field PIC X(1).
PROCEDURE DIVISION USING Data-Field.
MAIN-LINE.
CALL "_ORSTR" USING BY REFERENCE Receiver,
BY REFERENCE Data-Field,
BY REFERENCE String-Two,
BY VALUE LENGTH OF Data-Field.
DISPLAY Receiver.
STOP RUN.
While the need for bit testing and/or bit setting is not an everyday requirement for most CL and COBOL applications, it is certainly a requirement that can be easily met when it arises with the use of the MI instructions ANDSTR and ORSTR. In future articles, we'll look at additional MI instructions that can further aid you in rapid application development of high-performing solutions.
Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at
MC Press books written by Bruce Vining available now on the MC Press Bookstore.
 |
||
 |
|
IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale
|
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