Easytrieve Macro Syntax

Canonical Prototype Format

1
2
3
4
MACRO [positional-count] positional-name ... keyword-name default-value ...
 
  * model statements — valid Easytrieve source with &PARAMETER references
MEND

Brackets show optional positional-count when you mix keyword parameters or need to document positional arity explicitly. Positional parameter names are identifiers without ampersands on the prototype; the body references them with ampersand prefix (&EMPNAME). Keyword parameters on the prototype appear as name followed by default value—the default expands when invocation omits that keyword.

Positional-Count Rules

Syntax Variant Examples

Positional-only macro

1
2
3
4
5
MACRO 2 NUMBER RESULT
  DEFINE CUBE_WORK S 6 N VALUE 000000
  CUBE_WORK = &NUMBER * &NUMBER * &NUMBER
  &RESULT = CUBE_WORK
MEND

Broadcom cube example uses two positional parameters. Invocation %CUBE 5 CUBE-OUT binds NUMBER to 5 and RESULT to CUBE-OUT. The body assigns into the field name passed as RESULT because &RESULT substitutes the actual parameter text.

Keyword-only macro

1
2
3
4
5
6
MACRO 0 RECLEN 150 BLKSIZE 1800
FILE PERSNL FB(&RECLEN &BLKSIZE)
  EMPNAME  17  8  A
MEND
 
%PERSNL-FILE RECLEN=200 BLKSIZE=2400

Positional-count zero signals no positional values on invocation. RECLEN defaults to 150 and BLKSIZE to 1800 unless the caller overrides with RECLEN=200 style pairs.

Mixed positional and keyword

1
2
3
4
5
6
MACRO 1 FILENAME DDNAME PERSNL
FILE &FILENAME FB(150 1800)
  * fields follow
MEND
 
%OPEN-FILE PAYROLL DDNAME=PAYROLL

One positional (FILENAME) must appear first on invocation; DDNAME keyword overrides default PERSNL when supplied.

MEND Termination

MEND closes the macro definition. The preprocessor returns to normal source processing after MEND. Nested macros each require their own MACRO/MEND pair. Placing executable JOB logic between MACRO and MEND by mistake ships that logic into every expansion—usually a compile error if JOB appears inside a library macro meant for FILE only.

MSTART for Instream Development

1
2
3
4
5
6
7
8
9
MSTART
MACRO
FILE TESTFILE FB(80 800)
  REC-DATA 1 80 A
MEND
MEND
 
%TESTFILE
JOB INPUT TESTFILE

MSTART/MEND pairs bound instream macro facility testing in development programs. Production programs should invoke macros from libraries instead of embedding definitions. Your installation may configure whether double MEND is required—follow local Macro Facility chapter guidance.

Macro Naming and Invocation Syntax

1
%PERSNL

Model Statement Syntax in the Body

Model statements obey Easytrieve language rules after substitution. If &FIELD expands to an invalid identifier, compile fails on the generated line. Ampersand attaches to parameter name without spaces (&NUMBER not & NUMBER). When parameter value must concatenate with literal text, place literals adjacent in the model: FILE &PREFIX DATA expands FILE PAY DATA when PREFIX is PAY.

Prototype Line Ordering

1. Word MACRO must lead the line.
2. Positional-count number when keywords exist or clarity demands it.
3. Positional parameter names in invocation order.
4. Keyword name and default value pairs.

Reordering positional names on the prototype reorders required invocation values—treat the prototype as a public API contract documented in comments.

Invalid Syntax Patterns

• PROC or END-PROC inside macro body when generating library definitions—valid only if you intend runtime procedures in expanded source.
• MACRO not first on prototype line due to leading spaces or comment placement errors.
• Missing positional-count when keyword parameters exist—preprocessor cannot split invocation tokens.
• Percent invocation inside macro body without nested macro support—verify Macro Facility rules before chaining.
• Parameter names exceeding identifier rules after substitution.

Syntax Compared to MACRO Statement Reference Page

The statements/macro page documents the MACRO keyword as a language statement. This page focuses on full macro definition syntax including MEND, MSTART, and invocation relationship. Both pages align with Broadcom 11.6 Define Macros and Macro Invocation topics.

Explain It Like I'm Five

MACRO is the title on a recipe card that lists blank spaces for ingredients. MEND is the bottom of the card where the recipe stops. When you cook, you write %RECIPE and fill in sugar and flour in the blanks—the card turns into real steps. If you forget MEND, the cookbook thinks everything after your recipe is still part of the same card and gets confused.

Exercises

1. Write a keyword-only macro with positional-count zero and two keyword defaults.
2. Fix a prototype missing positional-count when a keyword parameter is present.
3. Document invocation syntax for a mixed macro with one positional and one keyword.
4. List five valid statement types for a FILE layout macro body.
5. Explain why MACRO must be the first word on the prototype line.