The CL Corner Working With Bits

MC Press Online
The CL Corner: Working with Bits

Contributed by Bruce Vining Thursday, 17 January 2008 Last 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 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.
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 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:
http://www.mcpressonline.com
Powered by Joomla!
Generated: 29 August, 2008, 00:24
MC Press Online
ANDSTR(
Receiver_string
:address of aggregate(*)
First_source_string
Second_source_string
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:
http://www.mcpressonline.com Powered by Joomla! Generated: 29 August, 2008, 00:24
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 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.
Powered by Joomla!
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,
Powered by Joomla!
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
First_source_string
Second_source_string
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 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')
Powered by Joomla!
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 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 highperforming solutions.
Powered by Joomla!

The CL Corner Working With Bits

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

The CL Corner Working With Bits

Uploaded by

Copyright:

Available Formats

MC Press Online

The CL Corner: Working with Bits

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

The first instruction, ANDSTR, is shown below and documented here:

Generated: 29 August, 2008, 00:24

:unsigned binary(4,8) value which specifies the

length of the three strings

Var(&Receiver) Type(*Char) Len(1)

Var(&String_Two) Type(*Char) Len(1) +

Type(*UInt) Len(4) Value(1)

Prc('_ANDSTR') Parm((&Receiver) (&Data) +

(&String_Two) (&Length *ByVal))

Cond(&Receiver = &String_Two) Then( +

SndPgmMsg Msg('The bit is on.') ToPgmQ(*Ext))

Cmd(SndPgmMsg Msg('The bit is off.') +

Here's the same program in COBOL:

Generated: 29 August, 2008, 00:24

LINKAGE TYPE SYS FOR "_ANDSTR".

PIC X(1) VALUE x"20".

PROCEDURE DIVISION USING Data-Field.

CALL "_ANDSTR" USING BY REFERENCE Receiver,

Generated: 29 August, 2008, 00:24

IF Receiver EQUAL String-Two DISPLAY "The bit is on."

ELSE DISPLAY "The bit off.".

The second instruction, ORSTR, is shown below and documented here.

:unsigned binary(4,8) value

which specifies the length of the

Var(&Receiver) Type(*Char) Len(1)

Var(&String_Two) Type(*Char) Len(1) +

Generated: 29 August, 2008, 00:24

Type(*UInt) Len(4) Value(1)

Prc('_ORSTR') Parm((&Receiver) (&Data) +

(&String_Two) (&Length *ByVal))

Here's the same program in COBOL:

LINKAGE TYPE SYS FOR "_ORSTR".

PIC X(1) VALUE x"10".

PROCEDURE DIVISION USING Data-Field.

CALL "_ORSTR" USING BY REFERENCE Receiver,

Generated: 29 August, 2008, 00:24

You might also like