Use this template when you create a deep-dive reference page for a single Db2 SQL statement (for example MERGE, TRUNCATE, or SET ASSIGNMENT). The goal is a page someone can open during coding or incident work and immediately see syntax, parameters, clauses, legal combinations, examples, rules, and the SQLCODEs that matter. Nested checklist items under each statement in the curriculum are sections to cover on that statement’s page—not separate URLs.
Copy the section headings below into a new tutorial page for one statement. Replace every placeholder with release-accurate Db2 for z/OS content. Prefer the licensed SQL Reference and your active function level over generic “SQL” folklore. Call out APPLCOMPAT and function-level gates whenever a clause is new.
Keep the page beginner-friendly but precise. Define terms once, show host-variable and dynamic-SQL notes where behavior differs, and link to locking, logging, triggers, and RI pages instead of restating the entire engine. Tasteful strong emphasis on the statement name and critical warnings is enough—avoid a summary section at the end.
Open with a readable railroad or lined syntax block that matches IBM’s clause order as closely as practical for teaching. Mark required versus optional clauses clearly. If the statement has multiple forms (for example searched versus positioned UPDATE), show each form in its own block and name them.
Document which contexts accept the statement: interactive tools, static embedded SQL, dynamic SQL, SQL PL, triggers, and routines. Note if the statement is not supported in a given context. Include a one-paragraph “what this statement does” before the diagram so skimmers still learn the purpose.
12345>>-STATEMENT-NAME--required-clause----+-----------------+->< '-optional-clause-' -- Teaching tip: keep syntax blocks short; move long option lists -- into the Parameters and Clauses sections with examples.
List every parameter, expression slot, and name placeholder. For each item explain data type expectations, nullability, special registers that influence it, and whether a host variable, parameter marker, or literal is allowed. If a parameter is a list (column lists, value lists), describe cardinality rules and duplicate handling.
Call out authorization IDs, schema resolution, and PATH / CURRENT SCHEMA effects when names are unqualified. When a parameter interacts with CCSID, datetime formats, or decimal precision, say so explicitly and point to casting rules.
Give each major clause its own subsection: purpose, when to use it, and what happens if you omit it. Explain mutually exclusive choices (for example different isolation or conflict-resolution clauses) as a decision list. If a clause changes locking, logging, or undo behavior, state that in one clear sentence and link deeper pages.
For predicates and assignment clauses, show indexability or stage concerns only when they are specific to this statement; otherwise link the predicates overview. Document order-of-operations inside the statement when IBM defines one (SET assignment order, MERGE WHEN matching order, and similar).
Authors often document clauses in isolation and leave readers to discover illegal mixes at bind or prepare time. Add an explicit combinations section: which clauses may appear together, which are exclusive, and which require a companion clause. Include at least one “legal” and one “illegal” example with the SQLCODE you expect.
Cover release-specific combinations separately. A combination that works at a higher function level may fail with a syntax SQLCODE on older APPLCOMPAT. State the minimum function level and recommended APPLCOMPAT for each advanced combination.
12345-- Pattern: show one valid combination STATEMENT ... CLAUSE_A ... CLAUSE_B; -- Pattern: show one invalid combination and expected failure mode STATEMENT ... CLAUSE_A ... CLAUSE_C; -- e.g. SQLCODE -199 / -104
Provide three tiers of examples: smallest possible success case, a realistic multi-clause case, and an embedded or dynamic variant if the statement is commonly used from programs. Use consistent sample table names across the curriculum when possible so readers can reuse lab data.
For each example, state the setup assumptions (table exists, unique index present, RI enabled) and the observable result (row counts, SQLCODE 0/+100, identity values). If the statement returns a result set or supports SELECT from data-change, show that form too.
Collect semantic rules that are easy to miss: authorization privileges required, object types allowed, restrictions with temporal tables, column masks, row permissions, triggers, views, and read-only targets. Mention transactional behavior: does the statement require a unit of work, can it run in atomic SQL PL blocks, and how SAVEPOINT interacts.
Document concurrency expectations at a high level (row locks versus table locks, whether the statement can escalate) and logging expectations (fully logged, minimal logging conditions, or not logged). Point to utility or LOAD paths when users confuse this statement with a bulk utility.
List the SQLCODEs readers hit most often for this statement: syntax, authorization, duplicate key, RI, check constraint, deadlock/timeout, and statement-specific codes. For each code give a one-line meaning and the first diagnostic action (check catalog privilege, verify predicate, retry after commit policy, and so on).
Do not paste the entire SQLCODE encyclopedia. Link cluster pages for ranges when helpful, and keep this section focused on codes that change interpretation because of this statement’s clauses. Include positive codes when they are meaningful (+100, +222, and similar).
A reference template is a blank worksheet with labeled boxes. Every time you teach a new SQL statement, you fill the same boxes: how you write it, what the knobs mean, which knobs can turn together, a few worked examples, the house rules, and the error codes you will see if you mess up. Same boxes, new statement.
1. What belongs in the clause-combinations section?
2. Why mention APPLCOMPAT on a statement page?
3. How many statement forms should syntax cover?