Macro arguments are the values callers pass when invoking %MACRONAME. They feed the preprocessor substitution engine that replaces ampersand references in the macro body with actual text before compile continues. Positional arguments rely on order—the first value maps to the first positional parameter declared on the MACRO prototype. Keyword arguments use NAME=value syntax and override defaults declared on the prototype. Mixed macros require positional-count so the preprocessor knows how many bare values to consume before reading keyword pairs. Beginners confuse arguments with PROC parameters; macro arguments exist only at compile time and never appear in the running load module as a parameter block. This page explains positional versus keyword design, default values, invocation ordering rules, substituting field names versus literals, special character considerations, and documenting parameter contracts for enterprise FILE macros shared across payroll, HR, and finance programs.
Positional parameters are declared as names on the MACRO line after optional positional-count. Invocation supplies values in the same order without naming them. Use positional arguments for the most common, stable inputs callers always provide—record keys, numeric constants, target field names. Positional invocation is compact: %CUBE 5 CUBE-OUT instead of NUMBER=5 RESULT=CUBE-OUT.
1234567MACRO 2 NUMBER RESULT DEFINE CUBE_WORK S 6 N VALUE 000000 CUBE_WORK = &NUMBER * &NUMBER * &NUMBER &RESULT = CUBE_WORK MEND %CUBE 5 CUBE-OUT
NUMBER receives 5; RESULT receives CUBE-OUT. Expanded source assigns into field CUBE-OUT because &RESULT substitutes the identifier text.
Keyword parameters declare as name default-value pairs on the prototype. When invocation includes DEPT=920, that value replaces &DEPT in the body. When invocation omits DEPT, the default from the prototype applies—critical for optional layout tweaks without breaking existing callers.
1234567MACRO 0 RECLEN 150 BLKSIZE 1800 LRECL 150 FILE PAYROLL FB(&LRECL &BLKSIZE) PAY-ID 1 9 N MEND %PAYROLL-FILE %PAYROLL-FILE RECLEN=200 BLKSIZE=2400 LRECL=200
| Situation | What &KEYWORD becomes |
|---|---|
| Keyword omitted on invocation | Prototype default value |
| KEYWORD=value supplied | Supplied value text |
| Empty value KEYWORD= | Follow site Macro Facility rules for empty actuals |
Broadcom requires all positional actual parameters before any keyword pair. Violating order makes the preprocessor attach values to wrong parameters—often producing bizarre FIELD names in listings.
123456789MACRO 1 FILENAME DDNAME PERSNL RECLEN 150 FILE &FILENAME FB(&RECLEN 1800) MEND * Valid %FILEMAC PAYROLL DDNAME=PAYROLL RECLEN=200 * Invalid — keyword before positional completes * %FILEMAC DDNAME=PAYROLL PAYROLL
The preprocessor scans model statements for &PARAMETER tokens. Each token replaces with invocation text verbatim—no automatic quoting. If you pass O'BRIEN as a character value needing quotes in DEFINE, include quotes in the actual parameter or in the model around &NAME. Concatenation happens when literals abut tokens: PREFIX&SUFFIX with PREFIX=ACCT and SUFFIX=NUM yields ACCTNUM in expanded source.
| You pass | Typical use in body | Example |
|---|---|---|
| Numeric literal 5 | Arithmetic or VALUE clause | CUBE_WORK = &NUMBER * &NUMBER |
| Field name CUBE-OUT | Assignment target or DEFINE name | &RESULT = CUBE_WORK |
| File name PAYROLL | FILE statement identifier | FILE &FILENAME FB(...) |
| Quoted literal | TITLE text or constant | TITLE 01 '&TITLE-TEXT' |
Every caller passing file name first benefits from short invocation. Document order in header comments on the macro member.
Record length changes for special runs become RECLEN=200 without forcing all legacy programs to add a new positional slot.
Beyond three positional parameters, callers mis-order values. Shift rarely changed inputs to keywords with defaults.
Actual parameters are tokenized per Macro Facility rules. Commas, quotes, and continuation lines may require escape or continuation columns depending on release and installation. When expansion produces invalid syntax, enable full macro listing (avoid NOMACROS) to inspect generated lines. Log ambiguous cases to your site research file if documentation is unclear.
| Aspect | Macro argument | PROC parameter |
|---|---|---|
| Lifetime | Compile-time only | Runtime working storage |
| Mechanism | Text substitution | Field references in logic |
| Invocation | %MACRO values | PERFORM with USING fields |
| Change without recompile | No—must recompile | Yes—values per call |
Positional arguments are filling blanks in order: first blank gets first sticker, second blank gets second sticker. Keyword arguments are stickers with labels: you put the red one on the spot marked color even if it is the third spot. Defaults are stickers already on the card until you replace them with a new one.
1. On invocation, positional values must appear:
2. Keyword parameter defaults apply when:
3. Body references substitute parameters with:
4. Positional-count on MACRO tells the preprocessor:
5. Passing a field name as positional argument lets the body: