Easytrieve String Functions Index

String Model in Easytrieve

Alphabetic type A fields have declared length in Library DEFINE or FILE field description. Shorter business values occupy left bytes; remainder fills with spaces unless you trim procedurally. Comparisons use collating sequence—typically EBCDIC on z/OS—so case and punctuation order matter. String functions and patterns must respect fixed length: assigning a ten-character result into A 5 truncates rightmost bytes unless you target a longer work field first.

Core String Capabilities Index

Overlay Substrings

Broadcom Getting Started documentation shows DATE-OF-BIRTH as six-byte N field with MONTH, DAY, YEAR overlays at positions 103–107. Same pattern applies to A fields: NAME- LAST as split on a fixed customer name field. Overlay does not copy data—it reinterprets bytes already in the parent. Changing MONTH updates parent bytes visible to other overlays. Overlays are compile-time views—fast and readable for fixed layouts like mainframe file records designed decades ago.

1
2
3
4
5
6
7
8
9
FILE INPUT-FILE
  CUST-NAME       1  30 A
    FIRST-NAME    1  15 A
    LAST-NAME    16  15 A
 
JOB INPUT INPUT-FILE
  IF LAST-NAME EQ 'SMITH'
     PRINT SMITH-RPT
  END-IF

INDEX and OCCURS Byte Walks

DEFINE SCAN-BYTE W 1 A OCCURS 30 INDEX SC-IX overlays a work buffer. Set SC-IX to position; compare SCAN-BYTE to delimiter or space; advance until condition met. INDEX formula: displacement equals (occurrence minus one) times element length. For one-byte OCCURS, index value maps directly to byte offset. Used for trim, delimiter parse, and search when no STRSRCH or Plus builtin exists. Loops belong in PROC or inline DO blocks; keep index bounds within field length to avoid reading past defined storage.

1
2
3
4
5
6
7
8
9
10
11
DEFINE WORK-NAME W 40 A
DEFINE CH       W  1 A OCCURS 40 INDEX CX
 
* Reverse scan for last non-space (trim pattern)
CX = 40
DO WHILE CX GT 0
  IF CH NE ' '
     LEAVE
  END-IF
  CX = CX - 1
END-DO

MOVE and Assignment for Strings

MOVE SOURCE TO TARGET copies bytes left-aligned into target length. Shorter source into longer target pads with spaces. Longer source into shorter target truncates right unless you use substring overlay first. Assignment NAME = LITERAL stores quoted constant with padding. Concatenation builds OUT-REC by MOVE part1 then overlay-assign part2 at offset using separate fields or sequential MOVE into pre-cleared buffer with MOVE SPACE TO OUT-REC first.

R2SCRIPT String Functions

Broadcom Workbench R2SCRIPT processor documents Command$, LCase$, and UCase$. Command$ returns command-line arguments with leading and trailing whitespace removed. LCase$ returns lowercase equivalent of expression; UCase$ returns uppercase. Syntax forms LCase$(expression) and UCase$(expression). These serve script automation—not every batch JOB activity environment. Do not assume R2SCRIPT functions compile in standard batch Report Generator programs without verifying your toolchain.

STRSRCH Legacy Macro

Broadcom knowledge base notes STRSRCH macro shipped with release 6.4 in SAMPJCL for string search but is not delivered with 11.x. Sites may copy from 6.4 CAIMAC or SAMPJCL member STRSRDOC instructions. Macro is third-party copyrighted—not Broadcom supported. Evaluate maintainability before adopting versus INDEX loop your team owns.

Trimming and Padding

Trimming removes trailing or leading spaces for compare and output. Padding adds spaces or zeros for fixed partner file layouts. Dedicated trimming tutorial covers reverse INDEX algorithm step by step. Padding tutorial covers RIGHT-JUSTIFY patterns for numeric strings in A fields. Both are procedural because TRIM and PAD builtins are absent on classic Report Generator.

Delimiter Parsing

Comma-separated or pipe-delimited extracts use DO WHILE with INDEX finding delimiter byte, MOVE segment to output field, shift remainder. State machine in PROC clearer than nested IF for many delimiters. Define segment W fields matching maximum token length. Log malformed lines to exception file when delimiter missing.

Comparison and Collating

IF NAME EQ LITERAL compares full field including trailing spaces unless you trim first. IF NAME GE 'A' AND NAME LE 'M' uses alphabetic range on EBCDIC order—not ASCII. Case sensitivity depends on data—UCase$ may normalize before compare in script contexts; batch jobs often store names already uppercased by upstream COBOL.

Performance Notes

Overlay access is cheapest—no loop. INDEX scan on thirty-byte field thirty times per million records adds CPU—consider pre-parse in upstream step or cache parsed tokens in W table when file is sorted by key. Hoist invariant uppercasing outside inner loop when Plus provides UCase$ equivalent callable in your environment.

Common String Mistakes

• Expecting SQL SUBSTR syntax without checking manual.
• Ignoring trailing spaces in EQ compare on A fields.
• INDEX bounds exceeding OCCURS count—undefined behavior.
• Overlay start location off by one relative to FILE record layout.
• Using R2SCRIPT function names in batch JOB without verification.
• Truncating concatenation silently into short target field.

Explain It Like I'm Five

String work is about words stored in boxes of fixed size. Overlay is drawing a smaller box inside the big box to read just the first few letters. INDEX is moving a finger one letter at a time until you find a space or comma. MOVE is copying letters from one box to another—extra room fills with blank spaces. Easytrieve does not always give a magic scissors tool—sometimes you cut by drawing smaller boxes or walking your finger.

Exercises

1. Define FIRST and LAST overlay on a thirty-byte A name field.
2. Write pseudocode for reverse INDEX trim on ten-byte field.
3. Explain when overlay beats INDEX loop for substring.
4. Compare MOVE padding behavior for five-byte source into ten-byte target.
5. Document whether STRSRCH or INDEX is standard at your site and why.