The CL Corner Working With Bits

7/27/2019 The CL Corner Working With Bits

http://slidepdf.com/reader/full/the-cl-corner-working-with-bits 1/10

The CL Corner: Working with Bits

Contributed by Bruce ViningThursday, 17 January 2008Last Updated Thursday, 17 January 2008

Sometimes the ability to test and/or set a specific bit is critical. By Bruce Vining

While the vast majority of commercial applications do not need to be concerned with individual bit values, every once in awhile you run across a support application-such as data collection or communications with another system-where theability to test and/or set a specific bit becomes critical. Some languages, such as RPG and C, provide direct support forthis type of operation. Other languages, with CL and COBOL coming quickly to mind, do not. Traditionally, I've seensome rather convoluted coding in CL and COBOL in order to work at the bit level. In this article, we'll look at a techniquethat greatly simplifies this type of work.

Sometimes the ability to test and/or set a specific bit is critical.

While the vast majority of commercial applications do not need to be concerned with individual bit values, every once in awhile you run across a support application-such as data collection or communications with another system-where theability to test and/or set a specific bit becomes critical. Some languages, such as RPG and C, provide direct support forthis type of operation. Other languages, with CL and COBOL coming quickly to mind, do not. Traditionally, I've seensome 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 arefamiliar with is Control Language (CL). Another language that is on every system however is Machine Interface (MI). Andone of the beauties of the i5/OS Integrated Language Environment (ILE) is that we can embed ILE MI directly into any ofthe 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). Inthis 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:

MC Press Online

http://www.mcpressonline.com Powered by Joomla! Generated: 29 August, 2008, 00:24



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

lengthof the three strings

The ANDSTR instruction performs a bit-by-bit ANDing of each byte of First_source_string, for the number of bytesspecified by String_length, to each corresponding byte of Second_source_string. The results of this operation arereturned in Receiver_string. So if we assume a bit-numbering convention of 0 to 7, where bit 2 being on is equivalent tob'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 couldANDSTR Data with the value x'20' (b'00100000') and know with confidence that if the returned Receiver_string is set tothis 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 withx'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 anunderscore. In reality, no CALL is being performed. The MI instruction is actually embedded directly into your applicationprogram.

In ILE CL, we can use ANDSTR as shown here with program TESTBIT:

MC Press Online




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))

MC Press Online




EndPgm

Calling this program with CALL TESTBIT x'20' will result in the message "The bit is on" being displayed. Entering CALLTESTBIT 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.

MC Press Online




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,

MC Press Online




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

MC Press Online




three strings

)

This instruction performs a bit-by-bit ORing of each byte of First_source_string, for the number of bytes specified byString_length, to each corresponding byte of Second_source_string. The results of this operation are returned inReceiver_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 wouldORSTR 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')

MC Press Online




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.

MC Press Online




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.

MC Press Online




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 iscertainly a requirement that can be easily met when it arises with the use of the MI instructions ANDSTR and ORSTR. Infuture articles, we'll look at additional MI instructions that can further aid you in rapid application development of high-

performing solutions.

MC Press Online


Documents

The CL Corner Working With Bits