Easytrieve LOW-VALUES

LOW-VALUES Is Hexadecimal Zero, Not Character Zero

Hexadecimal X'00' has all eight bits off. It differs from the character '0', whose EBCDIC byte is normally X'F0', and from a space, normally X'40'. A four-byte field filled with LOW-VALUES contains X'00000000'. A four-character field containing '0000' contains X'F0F0F0F0'. Those fields can look conceptually similar to a beginner but compare, sort, and validate differently.

1
2
3
4
5
6
7
DEFINE RAW-KEY W 8 A
 
MOVE LOW-VALUES TO RAW-KEY
 
IF RAW-KEY LOW-VALUES
   DISPLAY 'RAW KEY CONTAINS HEX ZEROES'
END-IF

LOW-VALUES expands to all eight bytes. The IF succeeds only when every position is X'00'. One space, digit, or letter causes the class test to return false.

Field-Class Condition Syntax

Use IF field-name [NOT] LOW-VALUES, DO WHILE, or DO UNTIL with the same field-class object. No EQ operator is needed. NOT LOW-VALUES means at least one position is not X'00'; it does not prove the field contains valid text or a valid number.

1
2
3
4
5
6
7
8
9
IF INPUT-CODE LOW-VALUES
   ERROR-CODE = 'L01'
   DISPLAY 'LOW VALUES IN INPUT CODE' RECORD-ID
ELSE
   IF INPUT-CODE NOT ALPHABETIC
      ERROR-CODE = 'L02'
      DISPLAY 'INVALID CODE CHARACTERS' RECORD-ID
   END-IF
END-IF

The first branch identifies the exact low-values sentinel. The second validates ordinary non-low content. This preserves meaningful error categories for upstream support teams.

Single-Byte, MIXED, and DBCS Rules

Broadcom documents LOW-VALUES as X'00' in every byte of single-byte and MIXED subjects and in each double byte of DBCS subjects. Define multilingual data correctly so Easytrieve understands the unit being tested. An arbitrary one-byte overlay of a DBCS field can split a character and create misleading validation results.

MOVE LOW-VALUES

Format 2 MOVE treats LOW-VALUES as a sending data area and fills each receiver. This is appropriate for binary buffers, raw key work areas, or protocols that explicitly require NUL bytes. It is not a general replacement for clearing business fields. Character output normally requires SPACES, and numeric output normally requires ZERO.

1
2
3
4
DEFINE FROM-KEY W 12 A
DEFINE RAW-FLAGS W 4 B
 
MOVE LOW-VALUES TO FROM-KEY RAW-FLAGS

FROM-KEY becomes a collating-low sentinel if the key protocol permits it. RAW-FLAGS becomes all zero bits. If RAW-FLAGS is used purely as a bit field, that can be a sensible cleared state. If it is interpreted as a signed numeric B quantity, use numeric ZERO when that intent is clearer.

LOW-VALUES Compared with ZERO

The packed-decimal distinction is especially important. A valid packed zero ends with a legal sign nibble such as C or F according to format. All raw zero nibbles leave the final sign nibble as 0, which can trigger S0C7 when arithmetic or conversion validates the field. Test a raw overlay for LOW-VALUES before referencing the packed field.

LOW-VALUES Compared with SPACES

Both patterns may render as empty on some screens, editors, or printers. Byte inspection tells them apart. IF NAME SPACES tests X'40' in each normal EBCDIC byte. IF NAME LOW-VALUES tests X'00'. Downstream CSV conversion, JSON encoding, sort keys, and database loads can react badly to embedded NUL bytes, so normalize only after logging where the low values came from.

1
2
3
4
5
6
7
8
IF CUSTOMER-NAME LOW-VALUES
   DISPLAY 'NAME WAS BINARY-ZERO FILLED' CUSTOMER-ID
   MOVE SPACES TO CUSTOMER-NAME
END-IF
 
IF CUSTOMER-NAME SPACES
   DISPLAY 'NAME IS NOW AN ORDINARY BLANK FIELD'
END-IF

Collating-Low Sentinel Keys

LOW-VALUES normally collates before ordinary EBCDIC character keys, so applications use it as a starting key or lower bound. A range can initialize FROM-KEY with LOW-VALUES and THRU-KEY with HIGH-VALUES. This works only when the access method and business key allow raw binary sentinels. A database may reject NUL bytes, and a VSAM application may impose key conventions. Always check FILE-STATUS after access operations.

Detecting Corrupt Numeric Input

File layouts often include packed amounts produced by COBOL or another mainframe product. If an upstream application clears the full record with binary zeros and forgets to assign an amount, the packed field may contain LOW-VALUES. Reading it directly as P and doing arithmetic can abend. Define an A or B overlay across the same bytes, test the overlay, and convert or reject before using the numeric view.

1
2
3
4
5
6
7
8
9
10
FILE CLAIMS FB(200 2000)
RAW-AMOUNT   80 5 A
CLAIM-AMOUNT RAW-AMOUNT 5 P 2
 
JOB INPUT CLAIMS
  IF RAW-AMOUNT LOW-VALUES
     DISPLAY 'INVALID LOW-VALUE AMOUNT' CLAIM-ID
     GOTO JOB
  END-IF
  TOTAL-AMOUNT = TOTAL-AMOUNT + CLAIM-AMOUNT

The raw overlay prevents Easytrieve from interpreting the bytes numerically before the class test. The exact overlay and field ordering must match the real record layout.

LOW-VALUES and NULL Are Different

SQL NULL is tracked by a null indicator, either generated by SQL INCLUDE NULLABLE or supplied manually as a two-byte quantitative binary field. A nullable character column can be NOT NULL while its data bytes contain LOW-VALUES, although such data may violate application expectations. Conversely, a NULL column can retain irrelevant bytes in its data area while the indicator says no known value exists. Use IF FIELD NULL for null status and IF FIELD LOW-VALUES for raw byte content only when that field format permits.

Report and Export Effects

NUL bytes can disappear, show as dots, truncate strings in non-mainframe tools, or produce invalid text encodings. Do not PRINT low values directly as though they were blanks. Derive a readable status, route the record to an exception report, or replace with spaces in an output-only field. Preserve original input for audit and diagnosis.

Working Storage Defaults

Easytrieve alphabetic working storage defaults to spaces and numeric working storage to zero. It does not default all fields to LOW-VALUES. If a raw buffer must begin with X'00', issue MOVE LOW-VALUES explicitly or use a verified hexadecimal VALUE. RESET returns W fields to their defined initial value, which is not automatically the LOW-VALUES pattern.

LOW-VALUES in Bit Fields

For a B field used as flags, all bits off is often a valid baseline. MOVE LOW-VALUES makes that byte-level intention explicit. Field-bits conditions can then test named masks. If the same B field is treated as a signed quantity, document whether all bits off means numeric zero and prefer the constant that best communicates the next operation.

Version and Portability Notes

LOW-VALUES is a documented reserved word in Easytrieve 11.6 and older CA-Easytrieve Plus releases. The X'00' definition is stable. External behavior is less universal: text converters, databases, sort tools, DBCS fields, and APIs handle NUL bytes according to their own rules. Verify every boundary where raw low values leave Easytrieve.

Common LOW-VALUES Mistakes

1. Treating LOW-VALUES as ordinary blank spaces.
2. Treating all-zero bytes as valid packed decimal zero.
3. Using LOW-VALUES when MOVE ZERO states numeric intent correctly.
4. Printing or exporting embedded NUL bytes without translation.
5. Assuming a database or VSAM operation accepts a low sentinel key.
6. Confusing low-value bytes with SQL NULL status.
7. Normalizing corrupt input before recording its source key.

Explain It Like I'm Five

Every computer box has eight tiny switches. LOW-VALUES turns every switch off. A SPACE is a real blank card with its own switch pattern, so it is not the same thing. Numeric ZERO is a properly written number zero with the right sign. If you put switch patterns into a money box that expects decimal digits, the calculator may not understand the amount.

Exercises

1. Move LOW-VALUES to an eight-byte raw field and test it.
2. Compare hexadecimal representations of LOW-VALUES, spaces, and character zeros.
3. Build a raw overlay that protects a packed amount from invalid low-value bytes.
4. Create FROM and THRU keys with LOW-VALUES and HIGH-VALUES and list access checks.
5. Explain why a nullable field containing X'00' can still be NOT NULL.
6. Write an exception report that translates low-value fields into readable messages.