Execution States

Every variable and operation result in OcaltQL carries a state. States are not types — they describe the condition of a value at the moment it is evaluated. Five states exist: true, false, NULL, EMPTY, and WAITING.

true

A variable is true when it holds a positive boolean value or when a condition succeeded. Set explicitly with AS true.

TRUE
SET ?flag AS true
AFTER IF ?flag IS true
OPEN
  EMIT "Yes"
CLOSE

false

A variable is false when it holds a negative boolean value or when a condition failed.

FALSE
SET ?flag AS false
AFTER IF ?flag IS false
OPEN
  EMIT "No"
CLOSE

NULL

A variable is NULL when it was never assigned, when an operation explicitly returned null, or when a failed operation produced no value. A variable that has never been set and a variable set to null are both NULL. NULL is distinct from EMPTY — NULL means no value exists at all.

NULL — Never Assigned
EMIT ?never_set
(* Output: null — variable was never declared *)
NULL — Returned Explicitly
NEW OPERATION maybe WITH ?x
OPEN
  IF ?x IS GREATER THAN 10
  OPEN
    RETURN ?x
  CLOSE
  OR
  OPEN
    RETURN null
  CLOSE
CLOSE
AFTER RUN maybe WITH 5 SET ?got
AFTER EMIT ?got
(* Output: null — condition failed, null returned *)

EMPTY

A variable is EMPTY when it exists but contains no content — an empty string, an empty array, or an empty object. EMPTY means the variable is set but has nothing in it. A pending PROMISE is WAITING, not EMPTY — see below.

EMPTY String and Array
STRING "" SET ?str
AFTER IF ?str IS EMPTY
OPEN
  EMIT "String empty"
CLOSE
EMPTY Array
NEW ARRAY SET ?arr
AFTER IF ?arr IS EMPTY
OPEN
  EMIT "Array empty"
CLOSE

WAITING

A variable is WAITING when it was created with SET PROMISE and the async operation has not yet resolved. It is not NULL — it exists and is actively pending. Once the operation resolves, the state changes to the actual value, or NULL on failure. A broken connection resolves to NULL — it is a valid resolution, not a special state.

WAITING State
FETCH "https://slow-api.com" SET PROMISE ?data
AFTER IF ?data IS WAITING
OPEN
  EMIT "Still loading"
CLOSE
Resolving a WAITING Promise
FETCH "https://slow-api.com" SET PROMISE ?data
AFTER WAIT FOR ?data SET ?result
AFTER IF ?result IS NULL
OPEN
  EMIT "Failed"
CLOSE
OR IF ?result IS NULL
OPEN
  EMIT "Connection failed"
CLOSE
OR
OPEN
  EMIT "Done: " & ?result
CLOSE

INFINITE

INFINITE is not a state a variable holds — it is a cause of FATAL. It occurs when a loop reaches the 1,000,000,000 iteration ceiling, or when a loop runs for more than 300 seconds without finishing. In either case the runtime aborts the script with a FATAL error. A script that has been aborted cannot test anything — there is no IS INFINITE operator.

INFINITE — Loop Without Termination
NUMBER 1 SET ?n
AFTER WHILE ?n IS GREATER THAN 0
OPEN
  CALCULATE ?n + 1 SET ?n
CLOSE
(* This loop never terminates. The runtime aborts it with a FATAL
   after 300 seconds of wall-clock time. The 1,000,000,000 iteration
   ceiling exists but is unreachable in practice — the wall-clock
   cap fires first. *)

State Checks

All states are checked with IF ?var IS [state]. IS SET checks only for the presence of a non-null value — it is true for any value that is not NULL and not unset. An empty string, an empty array or object, false, 0, a WAITING promise are all SET. IS SET, IS EMPTY and IS WAITING are independent checks, not mutually exclusive — a variable can be both SET and WAITING at the same time.

Full State Check Reference
IF ?var IS NULL
AFTER IF ?var IS EMPTY
AFTER IF ?var IS WAITING
(* IS INFINITE does not exist — INFINITE is a FATAL cause, not a state *)
AFTER IF ?var IS true
AFTER IF ?var IS false
AFTER IF ?var IS SET
State summary:
true — boolean positive or condition passed.
false — boolean negative or condition failed.
NULL — no value. Never set or explicitly null.
EMPTY — exists but has no content.
WAITING — PROMISE pending, not yet resolved.
INFINITE — broken, unresolvable, or endless state.
IS SET — true for any non-null, declared value. Not exclusive with EMPTY, WAITING, or INFINITE.
Header & Globals →