Easytrieve SPACE and SPACES

SPACE Is a Figurative Constant

SPACE is not a one-byte field that Easytrieve copies once. It is a figurative constant: Easytrieve expands the idea of a space to the length required by the operation. In a field-class condition, the subject controls how many bytes are inspected. In a MOVE, the first receiving field controls the default sending length, and every receiving field is set to the appropriate blank representation. This lets one statement clear fields of different lengths without coding separate quoted literals containing ten, twenty, or eighty blanks.

1
2
3
4
5
6
7
8
DEFINE WS-NAME     W 20 A
DEFINE WS-ADDRESS  W 40 A
 
MOVE SPACES TO WS-NAME WS-ADDRESS
 
IF WS-NAME SPACES
   DISPLAY 'NAME HAS NOT BEEN ENTERED'
END-IF

The MOVE clears all twenty bytes of WS-NAME and all forty bytes of WS-ADDRESS. The IF then inspects all twenty bytes of WS-NAME. It does not merely look for a blank somewhere in the field. Fixed-width names often contain trailing blanks, so a test meaning “contains any blank” would reject almost every normal record. The Easytrieve class condition instead answers the useful question: “Is this whole field blank?”

SPACE and SPACES Are Equivalent

Broadcom accepts both spellings in field-class conditions and in Format 2 of MOVE. There is no singular-versus-plural length rule. IF CODE SPACE and IF CODE SPACES both inspect the complete CODE field. MOVE SPACE TO NAME and MOVE SPACES TO NAME both blank the complete receiving field. Teams often prefer SPACES because the word visually suggests a repeated fill, while others prefer SPACE because it matches the name of the character class. Pick one in a coding standard so maintenance programmers do not waste time looking for a semantic difference that does not exist.

How the Field-Class Test Works

For single-byte and MIXED-format subjects, Easytrieve tests each byte for the space character. On z/OS using EBCDIC, an ordinary blank is hexadecimal 40. The test does not trim the field, collapse whitespace, or regard tabs and low values as blank. Every byte must match the expected space character. DBCS subjects follow the product's double-byte rules, so applications using Japanese or other DBCS data should confirm the field format rather than treating every character field as single-byte.

Using NOT SPACE for Required-Field Validation

The optional NOT reverses the field-class result. IF NAME NOT SPACES means at least one byte is not blank. That can be useful as a quick presence test, but it does not prove that the contents are valid. A name containing a low value, punctuation, or a single invalid byte is also NOT SPACES. Combine presence validation with ALPHABETIC or a business lookup when data quality matters.

1
2
3
4
5
6
7
8
9
IF CUSTOMER-NAME SPACES
   ERROR-CODE = 'N01'
   DISPLAY 'CUSTOMER NAME IS REQUIRED'
ELSE
   IF CUSTOMER-NAME NOT ALPHABETIC
      ERROR-CODE = 'N02'
      DISPLAY 'CUSTOMER NAME CONTAINS INVALID DATA'
   END-IF
END-IF

The first branch identifies the precise all-blank condition. The second branch handles nonblank data that does not satisfy the alphabetic class. Keeping these cases separate produces better diagnostics than a single broad test.

MOVE SPACES Before Reusing an Output Record

Easytrieve does not provide COBOL's group-level INITIALIZE for a hierarchy of fields. Output record layouts are normally cleared field by field or through a parent overlay. Before building a new output record, blank character destinations and zero numeric destinations. Otherwise, bytes left by the previous input record can leak into the next output record when a branch does not assign every field.

1
2
3
4
5
6
7
8
9
10
11
12
13
PROC CLEAR-OUTPUT.
  MOVE SPACES TO OUT-NAME OUT-ADDRESS OUT-MESSAGE
  MOVE ZERO TO OUT-AMOUNT OUT-COUNT
END-PROC
 
JOB INPUT CUSTOMER
  PERFORM CLEAR-OUTPUT
  OUT-NAME = CUSTOMER-NAME
  IF ADDRESS-VALID
     OUT-ADDRESS = CUSTOMER-ADDRESS
  END-IF
  PUT OUTPUT-FILE
END-JOB

Clearing OUT-ADDRESS matters because ADDRESS-VALID might be false. Without the blank fill, the output could retain the preceding customer's address. This is a data-integrity problem, not merely a display issue.

SPACE Compared with ZERO, NULL, and LOW-VALUES

A blank amount is not necessarily zero. A blank phone number is not necessarily NULL. A low-value-filled key is not blank. Mainframe files often use different sentinels for different business states, so replacing every “empty-looking” value with SPACES can erase meaning. Consult the record layout and database definition before normalizing values.

Spaces in Nullable Fields

Broadcom's MOVE rules state that moving spaces or zeros to a nullable receiving field sets that field to NOT NULL. This distinction is essential. MOVE NULL TO PHONE says no known phone value exists. MOVE SPACES TO PHONE says a known value exists and its character bytes are blank. SQL predicates, extracts, and downstream programs can treat those states differently. Use MOVE NULL only when the business value is absent, and MOVE SPACES only when blank data is the intended non-null value.

Default Initialization of Alphabetic Working Storage

Alphabetic W and S working-storage fields initialize to blanks when VALUE is omitted. Therefore a newly allocated DEFINE WS-FLAG W 1 A normally satisfies IF WS-FLAG SPACE. Adding VALUE makes a different initial state explicit. RESET on a W field returns it to its initial value at JOB, SCREEN, or SORT execution; if no VALUE is supplied, that means blanks for an alphabetic field.

1
2
3
4
5
6
7
8
9
10
DEFINE WS-REASON W 30 A RESET
DEFINE WS-SWITCH W  1 A VALUE 'N' RESET
 
JOB INPUT CLAIMS
  IF WS-REASON SPACES
     DISPLAY 'NO REASON HAS BEEN SET'
  END-IF
  IF WS-SWITCH NOT SPACE
     DISPLAY 'SWITCH HAS AN EXPLICIT VALUE'
  END-IF

Spaces in Fixed-Width Files

Fixed-block and variable-block datasets commonly pad character fields on the right. A ten-byte state description might hold ALABAMA followed by three spaces. It is NOT SPACES because letters remain. When comparing a fixed-width field to a literal, Easytrieve handles lengths according to assignment and comparison rules; the SPACE class test is specifically for detecting an entirely blank area. Do not use it as a trim operation.

Spaces in Reports

Blank character fields usually print as empty columns. They still occupy the report position calculated from LINE layout, headings, and spacing options. A field that is SPACES is not automatically omitted from a LINE statement. If an entire line should be suppressed, test the field before PRINT or use report procedures designed for conditional output. Numeric MASK BWZ is a separate feature that suppresses an all-zero numeric print value; it is not a SPACE test.

Data Cleaning Without Destroying Evidence

Legacy extracts may contain a mixture of spaces, zeros, low values, and malformed bytes. Test and count each condition before overwriting it. A cleanup job can display the record key and classify the problem, write rejected records to a separate file, and normalize only after the business owner confirms the mapping. Turning every abnormal byte pattern into spaces makes the output look cleaner but removes evidence needed to identify the producing system.

• Use SPACE to identify all-blank character fields.
• Use ALPHABETIC to validate letters and permitted spaces.
• Use LOW-VALUES to detect binary zeros separately.
• Use NULL only on fields defined as nullable.
• Log the record key before changing invalid content.

Version and Encoding Considerations

SPACE and SPACES are long-standing Easytrieve keywords and remain documented in Broadcom Easytrieve Report Generator 11.6. The logical behavior is stable, but byte representation depends on the host character set and field format. On normal EBCDIC single-byte z/OS data, a blank is X'40'. Do not hard-code hexadecimal 40 when SPACE communicates the intent more clearly and lets Easytrieve apply the correct representation. DBCS and MIXED fields have format-specific tests described in the current Field Class Condition documentation.

Common SPACE and SPACES Mistakes

1. Assuming SPACES means the field contains at least one blank.
2. Testing an all-blank name with ZERO instead of SPACE.
3. Using SPACE and NULL interchangeably for database columns.
4. Clearing character fields but leaving numeric output fields from the prior record.
5. Moving SPACES to packed fields instead of using ZERO.
6. Treating LOW-VALUES as blank because a terminal renders it invisibly.
7. Expecting a SPACE report field to remove its entire report column.

Explain It Like I'm Five

Imagine a row of twenty boxes for a name. SPACE asks whether every one of the twenty boxes contains a blank card. If even one box contains the letter A, the answer is no. MOVE SPACES replaces every card in the row with a blank card. NULL is different: it is a note saying nobody knows whether there should be a name. LOW-VALUES is also different: it fills the boxes with a special invisible computer marker instead of blank cards.

Exercises

1. Define a thirty-byte alphabetic work field and test its default content with SPACES.
2. Write validation that distinguishes blank NAME from a non-alphabetic NAME.
3. Clear three alphabetic and two numeric output fields in one procedure.
4. Explain why MOVE SPACES to a nullable phone field makes it NOT NULL.
5. Classify blank, numeric-zero, low-value, and SQL-null fields using the correct tests.
6. Modify a report job so records with a blank required code go to an error report.