docs/derived-variables.md

@@ -20,6 +20,7 @@ Each row defines one variable:
 
  - `LIBREF` / `DSN` - the target table
  - `VARIABLE_NM` - the name of the new column
+ - `VARIABLE_ORDER` - evaluation order; a variable may reference one with a lower order
  - `VARIABLE_TYPE` - `C` for character, `N` for numeric
  - `VARIABLE_LENGTH` - character length, or numeric length (1-8)
  - `VARIABLE_FORMAT` - optional, eg `DATE9.` or `DOLLAR12.2`
@@ -30,6 +31,7 @@ A simple example, deriving a region from a state:
 
 ```
 VARIABLE_NM      REGION
+VARIABLE_ORDER   10
 VARIABLE_TYPE    C
 VARIABLE_LENGTH  8
 VARIABLE_FORMAT  (blank)
@@ -37,6 +39,18 @@ VARIABLE_LOGIC   ifc(STATE in ('CA','OR','WA'),'West','East')
 ACTIVE           1
 ```
 
+A later variable can build on it, provided its order is higher:
+
+```
+VARIABLE_NM      REGION_LABEL
+VARIABLE_ORDER   20
+VARIABLE_TYPE    C
+VARIABLE_LENGTH  14
+VARIABLE_FORMAT  (blank)
+VARIABLE_LOGIC   cats(REGION,'-',STATE)
+ACTIVE           1
+```
+
 For each row, Data Controller generates the following statements when the table is read:
 
 ```sas
@@ -57,7 +71,7 @@ Derived columns themselves are an EDIT screen feature: the VIEW screen and the d
 ## Rules and limits
 
  - **Expressions only.** `VARIABLE_LOGIC` must be a single SAS expression - no semicolons, macro triggers (`%`, `&`) or comments. Conditional logic is available through functions such as `ifc()`, `choosec()`, `cats()`, `catx()`, `put()`, `input()` and `intnx()`.
- - **Self-contained.** An expression may reference the columns of the target table only, not another derived variable. Derived variables are evaluated independently of each other.
+ - **Ordered.** Statements are generated in `VARIABLE_ORDER` sequence. An expression may reference the physical columns of the table, and any derived variable with a lower `VARIABLE_ORDER`. A reference to a variable that is not defined earlier is rejected, because SAS would otherwise return a missing value without an error. `VARIABLE_ORDER` is required, and must be a positive integer.
  - **No collisions.** `VARIABLE_NM` must not match an existing column of the target table, or one of the reserved names (`TX_FROM`, `TX_TO`, `PROCESSED_DTTM`, `VAR_TXFROM`, `VAR_TXTO`, `VAR_PROCESSED`, `_____DELETE__THIS__RECORD_____`).
  - **Read-only.** Derived columns cannot be edited in the grid, and any value submitted for them is discarded before the approval package is created.
  - **Recomputed on every read.** The value always reflects the current data and the current definition, and there is no history of previous derived values.

docs/tables/mpe_derived.md

@@ -17,6 +17,7 @@ The table is itself registered in [MPE_TABLES](/tables/mpe_tables/), so it is ma
  - 🔑 `LIBREF char(8)`: The libref of the target table
  - 🔑 `DSN char(32)`: The target table
  - 🔑 `VARIABLE_NM char(32)`: The name of the derived column
+ - `VARIABLE_ORDER num`: Evaluation order; a variable may reference one with a lower order
  - `VARIABLE_TYPE char(1)`: `C` for character, `N` for numeric
  - `VARIABLE_LENGTH num`: Character length, or numeric length (1-8)
  - `VARIABLE_FORMAT char(32)`: Optional SAS format, eg `DATE9.`