3.5.2 Instruction
An Instruction is one entry of an InstructionList (RD-VBAL §3.5.1 InstructionList).
Fields
Every instruction carries its Offset, the source Node it was lowered from, and an
InstructionKind. The kind tells the interpreter
which of the resolved-target fields to consult, if any.
| Field | Holds |
|---|---|
Offset |
The instruction's own offset: its index in InstructionList.Items. |
Node |
The StatementNode the instruction was lowered from; null for a synthesized instruction (RD-VBAL §3.5.3 Lowering Block Statements). |
Kind |
The InstructionKind. |
Target |
A single resolved offset, for the kinds that branch to one place. |
Targets |
One resolved offset per label, in source order, for JumpTable and GoSubTable. |
Else |
For ConditionalBranch: the offset to go to on false or no match. |
End |
On a block's opening instruction: the offset right past the block. |
Matching |
The offset of the block-opening instruction whose state this instruction reads back: a Case header names its Select opener; a ForNext or ForEachNext names its own opener. |
EnclosingWith |
The offset of the innermost With opener lexically enclosing the instruction. |
Instruction kinds
The table below lists what each statement lowers to. Each linked RD-VBAL §5.4 page implements the MS-VBAL section of the same number, and defines the statement's runtime semantics.
| Statement | InstructionKind | Resolved target(s) | Semantics |
|---|---|---|---|
GoTo |
Jump |
Target: the label's offset. |
RD-VBAL §5.4.2.12 GoTo Statement |
On expression GoTo label, ... |
JumpTable |
Targets: one offset per label, in source order. A selector out of range falls through at runtime instead of branching. |
RD-VBAL §5.4.2.13 On...GoTo Statement |
GoSub |
GoSub |
Target: the label's offset. |
RD-VBAL §5.4.2.14 GoSub Statement |
Return |
Return |
— | RD-VBAL §5.4.2.15 Return Statement |
On expression GoSub label, ... |
GoSubTable |
Targets: one offset per label, in source order. |
RD-VBAL §5.4.2.16 On...GoSub Statement |
Exit Sub, Exit Function, Exit Property |
ExitProcedure |
— | RD-VBAL §5.4.2.17 Exit Sub Statement, RD-VBAL §5.4.2.18 Exit Function Statement, RD-VBAL §5.4.2.19 Exit Property Statement |
Exit For, Exit Do |
ExitLoop |
Target: the offset right past the closer of the innermost enclosing loop of the matching kind. |
RD-VBAL §5.4.2.5 Exit For Statement, RD-VBAL §5.4.2.7 Exit Do Statement |
Stop |
Break |
— | RD-VBAL §5.4.2.11 Stop Statement |
End |
Halt |
— | RD-VBAL §5.4.2.22 End Statement |
If or ElseIf header; single-line If |
ConditionalBranch |
Else: the offset to go to on false: the next header in the chain, the first instruction of the Else body, or right past the whole construct. |
RD-VBAL §5.4.2.8 If Statement, RD-VBAL §5.4.2.9 Single-line If Statement |
Case header |
ConditionalBranch |
Else: the offset to go to on no match: the next header in the chain, the first instruction of the Case Else body, or right past the whole construct. Matching: the offset of its Select opener. |
RD-VBAL §5.4.2.10 Select Case Statement |
Pre-test loop header: While…Wend, Do While, Do Until |
ConditionalBranch |
Else: right past the whole loop. |
RD-VBAL §5.4.2.2 While Statement, RD-VBAL §5.4.2.6 Do Statement |
| Pre-test loop back-edge (synthesized) | Jump |
Target: the loop's header. |
RD-VBAL §5.4.2.2 While Statement, RD-VBAL §5.4.2.6 Do Statement |
Do…Loop While, Do…Loop Until closer |
LoopBack |
Target: the body's first instruction, taken when the loop continues. Falling through ends the loop. |
RD-VBAL §5.4.2.6 Do Statement |
Bare Do…Loop back-edge |
Jump |
Target: the body's first instruction. |
RD-VBAL §5.4.2.6 Do Statement |
For opener / Next closer |
ForOpener / ForNext |
Opener's End: right past the Next. Next's Target: the body's first instruction. Next's Matching: the opener's offset. |
RD-VBAL §5.4.2.3 For Statement |
For Each opener / Next closer |
ForEachOpener / ForEachNext |
The same shape as For. |
RD-VBAL §5.4.2.4 For Each Statement |
With opener |
With |
End: right past the block. Every instruction inside the block carries EnclosingWith = this opener's offset. |
RD-VBAL §5.4.2.21 With Statement |
Select Case opener |
Select |
End: right past the block. Each Case header's Matching names this opener's offset. |
RD-VBAL §5.4.2.10 Select Case Statement |
On Error GoTo label |
OnErrorGoTo |
Target: the label's offset. |
RD-VBAL §5.4.4.1 On Error Statement |
On Error GoTo 0, On Error GoTo -1 |
OnErrorDisable |
— | RD-VBAL §5.4.4.1 On Error Statement |
On Error Resume Next |
OnErrorResumeNext |
— | RD-VBAL §5.4.4.1 On Error Statement |
Resume, Resume 0 |
ResumeCurrentStatement |
— | RD-VBAL §5.4.4.2 Resume Statement |
Resume Next |
ResumeNext |
— | RD-VBAL §5.4.4.2 Resume Statement |
Resume label |
ResumeLabel |
Target: the label's offset. |
RD-VBAL §5.4.4.2 Resume Statement |
Error number |
RaiseError |
— | RD-VBAL §5.4.4.3 Error Statement |
The trailing jump of an If/ElseIf/Else or Case/Case Else branch (synthesized) |
Jump |
Target: right past the whole construct. |
RD-VBAL §3.5.3 Lowering Block Statements |
| Every other statement | Simple |
— | RD-VBAL §3.5.4 Execution (dispatch by statement type) |
A label operand that does not resolve, and an Exit For/Exit Do with no enclosing loop of the matching kind,
leave the target null; see RD-VBAL §3.5.3 Lowering Block Statements.
The Matching field
A ForNext instruction uses the same Instruction.Matching field that a Case header uses for its
back-reference to its Select. The two uses are never ambiguous, because InstructionKind alone picks which
interpretation applies.
Design
Tip
A statement's own runtime semantics stay pure: they evaluate operands and return a result, and never mutate
control state. InstructionKind and the pre-resolved offsets on Instruction let the interpreter's
fetch/decode loop decide whether to branch, without the statement semantics needing to know about the
program counter (RD-VBAL §3.5.4 Execution).
⏮️ RD-VBAL §3.5.1 InstructionList | ⏭️ RD-VBAL §3.5.3 Lowering Block Statements