TLF Macro Patterns & Debugging

A listing macro can run clean — zero errors, zero warnings — and still ship an empty table, listing, or figure — an empty TLF. You open the one Rich Text Format file — the one RTF on disk — and find headers only, no data rows; that is the failure mode this course exists to prevent in clinical listing quality control, QC. The log shows what SAS executed, and what SAS executed is the code your macro generated, not the code you typed. A hidden WHERE clause can resolve against a flag value that simply is not in this data cut. Over the next scenes we follow a roadmap: the metadata-table driver pattern, parameter discipline, %local hygiene, then MPRINT, SYMBOLGEN, and MLOGIC debugging. Every displayed value and code line traces to the source — no simulated counts.

Here is the pattern that makes a macro worth writing. A Tables, Listings, and Figures output, a TLF, repeats the same moves: filter a population from the Subject-Level Analysis Dataset, ADSL, count subjects by treatment, lay out columns, hang titles and footnotes, write the Rich Text Format, RTF, file. What differs between two outputs is small: the output ID, the population flag, the title set, maybe the sort order. Hard-code one block per treatment column and a column-order change edits every block; the one you miss ships. At review, that miss reads as an analysis error, not a typo. So macros pay off when the logic repeats across outputs, populations, or treatment columns, and a one-off stays a plain program.

Here is the driver pattern: the logic lives once, in the workhorse macro %mk_listing, and the variation lives in metadata. That metadata table, tlfmeta, holds one row per output, with columns outid, popfl, and ttl1. Its three rows are 14.1.1 for Summary of Demographics, 16.2.1.1 for Assignment to Analysis Populations, and 16.2.2.1 for Adverse Events by System Organ Class, each with a population flag of SAFFL. The driver macro, %drive_listings, declares %local i nouts, reads the row count into :nouts and every row into :id1-, :fl1-, and :t1- using SQL INTO, then loops %do i = 1 %to &nouts. Inside that loop it calls %mk_listing with data=adam.adsl, outid=&&id&i, popfl=&&fl&i, and ttl1=&&t1&i. Notice the two-step &&id&i: it only resolves when the call executes, so SYMBOLGEN will show you each step later.

Here is the workhorse contract. Everything the macro needs arrives through keyword parameters — data=, outid=, popfl=, and ttl1= — so the macro reads no global on the side and depends on no hidden %let chain. The second rule is %local hygiene: every macro variable the macro creates gets %local, indexes and counters declared first, and mk_listing declares %local nsub before it counts subjects. The failure recipe is two macros looping with an index named i where only one declares %local i; the helper's %do loop overwrites the driver's copy, so the loop restarts, repeats a block, or skips an output. No error appears in the log, yet the same leak can ship 16.2.1.1 twice while 16.2.2.1 never appears. Titles and the ODS destination belong inside the macro, so one call gives one complete output, with nothing inherited and nothing leaked.

Here is the debugging trio: MPRINT, SYMBOLGEN, and MLOGIC. Switch all three on together for a debugging run with options mprint symbolgen mlogic; and turn them off for the validated run. A clean run that produces an empty table usually means the population filter resolved to nothing, so the first switch is MPRINT: read the WHERE clause that actually ran. Healthy evidence looks like SYMBOLGEN reporting that the macro variable POPFL resolves to SAFFL, followed by MPRINT(MK_LISTING): where SAFFL = "Y" ;. If the resolved line instead reads where POPFL = "Y", someone passed the flag value instead of the variable name, and you have found the bug in ten seconds. Wrong counts or a stale N point to SYMBOLGEN, while repeated blocks or a runaway loop send you to MLOGIC, which traces each %DO boundary.

This checkpoint quiz covers the core metadata contract and macro hygiene patterns before the walkthrough and interactive debugging practice. First, in a metadata-driven Table, Listing, and Figure, or TLF, program, what is the primary contract between one row of the tlfmeta table and the reporting macro that the driver calls? The correct answer is A: the row supplies macro-parameter values, such as the TLF name, source data set, and population flag variable names, to the reporting macro, because each row represents one requested output and the driver turns its column values into macro-parameter values, passing population flags such as saffl as variable names. Next, if a driver macro runs %DO I = 1 %TO ... and calls a helper macro that also uses I but does not declare it %local, what is the risk and the correct hygiene rule? The correct answers are A and B: temporary variables used only by the helper, including its loop index, should be declared %local, and if the driver's &I is not %local, a helper writing to &I can alter the driver's loop counter, producing a repeated output block or unexpected loop behavior; statements recommending %global or claiming SYMBOLGEN repairs overrides are incorrect. Finally, which first-debugging-switch pairings correctly match a macro-driven TLF failure symptom to the SAS option to turn on? The correct answers are A, B, and C: empty output with MPRINT to confirm the expected data step or PROC REPORT code was generated and executed; wrong counts with SYMBOLGEN to inspect whether population-flag and source-data macro variables resolved as intended; and repeated block with MLOGIC to trace %DO loop execution, including whether the loop index is reset after a helper macro call, because MPRINT shows generated SAS statements, SYMBOLGEN shows macro variable resolution, and MLOGIC traces macro execution and loop flow.

Let's follow one metadata row through the table, listing, and figure (TLF) pipeline. When the driver loop reaches row 16.2.1.1, it calls the workhorse with outid, popfl, and ttl1 taken straight from that row. So outid becomes 16.2.1.1, popfl becomes SAFFL, and ttl1 becomes Assignment to Analysis Populations. Inside the workhorse, popfl holds the variable name SAFFL, so the macro emits the filter SAFFL = "Y" — it never looks up a flag value. That same flag drives the header count, which uses the unique subject identifier, or USUBJID: select count(distinct usubjid) from &data where &popfl = 'Y'. Because the count and the body rows share that flag, the N in title2 cannot diverge from the body rows — and all these values trace to source metadata, not to any patient-level data.

This exercise is done hands-on on the website, so open jaimeyan.com/learn in your browser rather than waiting for the video. You will practise reading resolved MPRINT and SYMBOLGEN evidence, classifying each symptom to its first switch, and marking every macro variable that needs a %local declaration in the drive_listings and mk_listing snippets. After you finish this video, go to jaimeyan.com/learn and try the exercise yourself, then validate your answers against healthy-call evidence where SYMBOLGEN resolves POPFL to SAFFL and MPRINT shows where SAFFL = "Y" ;

Three anti-patterns share one root: variation stored in code instead of in data. Six-level nesting—%mk calls %fmt calls %pop calls %cnt—makes resolved code unreadable, and nobody, including you, can quality control (QC) it. Macro-as-configuration puts forty %let statements at the top, read silently; changing one value is archaeology and breaks the second caller. Copy-paste output forks like %tab141, %tab142, and %tab143 let a fix land in one fork while the rest drift until the next data cut. Here is the portability test: run the macro against shells from three different studies; if each study still needs its own edit, you wrote a template, not a macro.

Beyond the macro, think about continuous integration, or CI. When shells are machine-readable, the driver is generated from them; the macro layer is unchanged, and metadata stops being hand-typed. Under Git and CI, every commit regenerates outputs, so a scope bug hidden interactively becomes a red build; parameter discipline protects the runner. The design ports: a tibble or DataFrame holds specs, one function per output replaces the workhorse, and walk or apply replaces the %do loop. Agent-drafted macros are volatile: they often omit %local and bury parameters in %let chains, creating second-call bugs. So call the macro twice from a driver under options mprint symbolgen mlogic, then list every macro variable it creates and where each is declared.

This is the final checkpoint: debug and decide. In the first question, you review a table, listing, and figure (TLF) macro that filters on unique subject identifier (USUBJID) during quality control (QC), and the SAS log shows an MPRINT line with a resolved WHERE clause. The correct answer is A: MPRINT prints resolved SAS statements, so this line confirms that &usubjid resolved to the expected USUBJID value in the emitted WHERE clause; SYMBOLGEN shows individual macro-variable resolutions, and MLOGIC shows execution flow, not generated SAS code. The second question asks how to fix a workhorse macro that changes a global macro variable because it omits %local. The correct answer is A: add %local keep; inside %apply_filter immediately after the macro header, so the %let affects only the local macro variable and protects the caller's global table. The third question asks which code structures are anti-patterns for rich text format (RTF) TLF generation, because variation belongs in a metadata table, not in code. The correct answers are A and C: table-specific %if branching inside the macro, and duplicated macro calls with hard-coded file names, input data sets, and filter subjects. For the short-answer question, the model answer is: run %make_tlf on three table shells whose metadata rows differ meaningfully, such as a subject-level analysis dataset (ADSL) table, an adverse event table, and a lab listing, changing only the metadata rows, and then call it a second time to confirm the macro produces the required RTF output without editing its source, which shows table-specific variation is in metadata rather than macro code.

Keep the logic once and drive variation from a metadata table — one row per output, with output ID, population flag, and title set — the pattern behind Tables, Listings, and Figures, or TLF, production. Everything enters as a parameter; declare %local for each variable it creates, indexes first; population flags come from the subject-level analysis dataset, or ADSL, keyed by the unique subject identifier, or USUBJID, and outputs render to Rich Text Format, or RTF. When a macro misbehaves, read the generated code: MPRINT for empty output, SYMBOLGEN for wrong values, MLOGIC for bad flow, all three on — your first quality control, or QC, step. Test three shells from different studies; if each needs an edit, it is a template, not a macro; this mirrors Bootcamp Part 18, no subject-level CSV rows were supplied, so no simulated patient counts appear.