Easytrieve Literals

Literals vs Identifiers

Identifiers name things—EMPNO, WS-TOTAL, CALC-TAX. Literals are the values themselves. The apostrophe is the primary signal: 'Y' is literal text, Y alone is a field reference if defined. Numeric literals look like numbers in other languages: 100, -45.67, +0. Hexadecimal literals use X'...' syntax for byte-level constants. Mixing these categories produces compile errors or wrong comparisons when a numeric literal is assigned to an alphabetic field without implicit conversion support.

Alphanumeric Literals

Alphanumeric literals are enclosed in single quotes and may be up to 254 characters long. They may contain letters A through Z and digits 0 through 9. On the mainframe, EBCDIC encoding applies; ASCII applies on UNIX and Windows per Broadcom platform notes. Use alphanumeric literals in IF comparisons, MOVE and assignment statements, TITLE and LINE report text, DISPLAY messages, VALUE clauses on DEFINE, and HEADING text.

1
2
3
4
5
6
7
IF STATUS EQ 'A'
   MOVE 'CLOSED' TO WS-MSG
END-IF
 
DEFINE WS-FLAG W 1 A VALUE 'Y'
 
TITLE 01 'PAYROLL LISTING FOR ' SYSDATE

Empty strings are valid: '' represents zero characters when business logic requires clearing or initializing text fields. Trailing spaces inside quotes are significant—'AB' and 'AB ' differ in length and comparison results.

Embedded Apostrophes

Because single quotes delimit literals, an apostrophe inside the text must be coded as two consecutive single quotes. The name O'KELLY becomes 'O''KELLY'. Forgetting to double the quote terminates the literal early and produces syntax errors or stray tokens the compiler cannot parse.

Numeric Literals

Numeric literals contain up to 18 digits. You may prefix a plus or minus sign for algebraic sign. A single decimal point indicates fractional precision up to 18 decimal positions total across the literal. Numeric literals appear unquoted in assignments, IF numeric comparisons, arithmetic expressions, and some parameter positions. All operands in pure arithmetic expressions must be numeric fields or numeric literals.

1
2
3
4
5
6
7
WS-COUNT = 0
WS-RATE  = +125.50
WS-DISC  = -0.075
 
IF GROSS GT 1000.00
   WS-BONUS = GROSS * 0.10
END-IF

Compare numeric literal precision to field DECIMALS on DEFINE. Assigning 123.456789012345678901 to a field with fewer decimal positions truncates or rounds per product rules and field type. Integer-looking literals like 42 still participate in packed, zoned, or binary conversion when assigned to typed numeric fields.

Hexadecimal Literals

Hexadecimal literals represent byte values not easily typed on a keyboard. Prefix with X and open a single quote: X'4040'. Each pair of hex digits compresses to one byte. Only 0-9 and A-F are permitted. Common uses include bit masks in AND, OR, and XOR expressions, initializing packed fields, and testing specific EBCDIC or binary bit patterns.

1
2
3
4
5
6
DEFINE F1P W 2 P MASK HEX
DEFINE F2P W 2 P VALUE X'123D'
 
F1P = F2P AND X'FFFE'
F1P = F2P OR  X'000F'
F1P = F2P XOR X'FFFF'

X'0000' defines two bytes of binary zeros. X'40' defines one byte (EBCDIC space in many code pages). Length in bytes equals half the count of hex digits inside the quotes—an odd digit count is invalid. When DISPLAY shows hex results, verify mask width matches field LENGTH to avoid truncating high-order bits.

DBCS and MIXED Format Literals

Sites processing double-byte character sets use DBCS literals enclosed in apostrophes with shift-out and shift-in codes marking DBCS subfields. MIXED literals combine single-byte (SBCS) and DBCS characters in one quoted string, also up to 254 bytes including shift codes. Beginners at ASCII-only shops may never code these, but multinational payroll and customer name fields depend on them. Continuation rules for DBCS literals require shift-in before the continuation character and shift-out before continuing DBCS on the next line.

Literal Subject Elements and Conversion

On the mainframe, the compiler converts literals to match the subject element of each statement—the field, file, printer, or terminal context that receives or compares the value. On an assignment to a zoned numeric field, a numeric literal converts with format rules documented in Literal and Data Formatting Rules. On IF against an alphabetic field, alphanumeric literals must be compatible or conversion applies. Unsupported format relationships produce compile errors rather than silent corruption.

Literals in Reports and DISPLAY

TITLE and LINE statements intermix literals with field names. Literals supply column headings, punctuation, and static labels; fields supply data values. DISPLAY uses the same pattern for batch log lines. Font numbers prefixed with # on some statements apply to fields and literals in extended report processing—#1 before a literal selects a font table entry per release documentation.

Continuing Long Literals

When a literal exceeds column 72, use minus or plus continuation at the end of the line. Broadcom examples split VALUE 'ABC- across lines with continuation to form one logical literal ABC-DEF. Do not insert comment lines inside a continued literal. See the continuation lines tutorial for minus versus plus resume positions when splitting mid-word.

Common Literal Mistakes

1. Using double quotes instead of single quotes—Easytrieve expects apostrophe delimiters.
2. Forgetting to double an embedded apostrophe in names like O'Brien.
3. Comparing numeric field to quoted number '100' instead of unquoted 100.
4. Hex literal with odd number of digits or invalid characters G through Z.
5. Assuming trailing spaces in literals are trimmed—they are part of the value.
6. Using hex masks wider than the target packed or binary field LENGTH.

Explain It Like I'm Five

A literal is a sticker you put directly on a box instead of writing a name tag that points somewhere else. 'HELLO' is the sticker with the word HELLO on it. 42 is a sticker with the number forty-two. X'FF' is a special sticker with secret machine codes only the computer reads easily. If your sticker has a quote mark inside the words, you draw two little marks so the computer knows the sticker has not ended yet.

Exercises

1. Code a literal for the name D'ANGELO using correct apostrophe doubling.
2. Write an IF that compares STATUS to the one-character literal A.
3. Create a hex mask assignment F1P = F2P AND X'00FF' and explain byte width.
4. State the maximum lengths for alphanumeric and numeric literals.
5. Explain why '100' and 100 are not interchangeable in all contexts.