Easytrieve Integer (Type I)

Declaring Type I Fields

Syntax matches other DEFINE attributes: name, location, length, I, optional decimal positions that must be blank or zero. WS-COUNT W 4 I defines a four-byte working storage integer. REC-CNT 100 2 I overlays two bytes at position one hundred in a file. Length must be exactly 2, 4, or 8—coding I 3 or I 5 fails validation because those sizes are not defined in the integer format family.

1
2
3
4
5
6
7
FILE CONTROL FB(80 800)
  REC-CNT   1  4 I
  STATUS   10  2 I
 
DEFINE WS-ITER   W 4 I VALUE 0
DEFINE WS-FLAGS  W 2 I
DEFINE WS-BIGINT W 8 I

Signed Integer Capacity

When decimal positions are specified as zero, I is quantitative signed integer using two's complement on z/OS. The high bit of the leftmost byte is the sign. Capacities follow standard binary integer ranges documented in the DEFINE statement reference.

Unsigned Integer Capacity

Omitting decimal positions on I makes the field non-quantitative unsigned in the same sense as other numeric types—storage interpreted as unsigned magnitude without signed arithmetic semantics. Unsigned maximums differ from signed maximums for two-byte fields especially.

Type I vs Type B

Both store binary data, but rules diverge. B allows lengths up to eight bytes with optional decimal positions 0–10 for quantitative binary fractions. B without decimals is ideal for bit masks and flag halfwords. I restricts length to 2, 4, or 8 and forbids fractional decimals—purpose-built for integer APIs. A COBOL PIC S9(9) COMP four-byte binary salary might map to I 4 or B 4 0 depending on copybook and shop standards; a status halfword with individual flag bits maps to B 2 non-quantitative, not I.

• Use I for record counts, array indexes, API return codes sized as binary int.
• Use B non-quantitative for bit fields and hardware flag words.
• Use B quantitative with decimals for rare fixed-point binary fractions.
• Use P or N for money—never I for employee gross pay.

Arithmetic and Assignment

I fields participate in arithmetic expressions with conversion to internal numeric forms. Adding WS-COUNT and 1 increments a loop counter. Overflow beyond capacity wraps or truncates per product rules—test boundary values. INTEGER assignment option truncates toward zero when receiving fractional results into integer targets. ROUNDED and TRUNCATED apply to other numeric types more often than I in business reports.

1
2
3
4
5
WS-ITER = WS-ITER + 1
IF REC-CNT GT 99999
   DISPLAY 'COUNT OVERFLOW RISK'
END-IF
WS-RESULT = (PART / TOTAL) * 100 INTEGER

Initialization and VALUE

Numeric working storage initializes to zero without VALUE. VALUE 100 on I 4 sets starting counter. FILE I fields read whatever bytes exist in the dataset—validate before arithmetic if files can contain LOW-VALUES. DISPLAY on I may show converted decimal for debugging; DISPLAY HEX shows raw big-endian bytes on z/OS.

COBOL COMP Mapping

COBOL COMP, COMP-4, and COMP-5 binary items align to I when byte length matches 2, 4, or 8 and the data is truly integer. SYNC and REDEFINES in copybooks affect starting positions— Easytrieve FILE position must match physical record layout. BINARY in DB2 sometimes exports differently—verify with hex display on sample records before production.

Endianness and Portability

I uses native host format. z/OS big-endian layout differs from Windows or Linux little-endian test harnesses. Extracting mainframe integers into PC-side analytics without byte swap produces nonsense values. Document endian assumptions when hybrid pipelines read I fields from copied datasets.

When Not to Use I

1. Currency, tax, and rate amounts needing implied decimals—use P.
2. Display numeric keys with leading zeros—often type N or A.
3. Single-byte counters—I has no one-byte length; consider N 1 0 or B 1.
4. Bit-level flag testing—use non-quantitative B with masks.

Explain It Like I'm Five

Type I is a click counter with only whole numbers—no half clicks allowed. It comes in three box sizes: small (2 bytes), medium (4 bytes), and huge (8 bytes). You cannot pick a custom-sized box. The counter knows plus and minus for medium and large boxes, but you would not use it to count pennies and dimes—that is a different counter with decimal slots called P.

Exercises

1. Define a four-byte working storage I counter initialized to zero.
2. State the maximum signed value storable in two-byte I.
3. Explain one scenario where B is better than I.
4. Write IF logic guarding against REC-CNT exceeding 999999 on I 4.
5. Describe why salary should not use type I.