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.
LATEST COMMENTS
MC Press Online