WAIT & SLEEP

OcaltQL provides three timing primitives. SLEEP pauses execution for a fixed duration. PROMISE marks a variable as pending — set it asynchronously while the script continues. WAIT blocks until a variable is no longer EMPTY, optionally with a timeout.

SLEEP

SLEEP pauses the current execution for a fixed duration. Units: MILLISECONDS, SECONDS, MINUTES, HOURS. The duration can be a literal or a variable.

Fixed Durations
SLEEP 500 MILLISECONDS
AFTER SLEEP 2 SECONDS
AFTER SLEEP 5 MINUTES
AFTER SLEEP 1 HOUR
Duration from Variable
NUMBER 3 SET ?duration
AFTER SLEEP ?duration SECONDS

PROMISE

SET PROMISE ?var marks a variable as pending. The operation that sets it begins immediately but does not block the next statement — the script continues while the value is being resolved in the background. The variable exists in state as WAITING until it resolves — see Execution States.

Non-Blocking Fetch
FETCH "https://api.example.com/data" SET PROMISE ?data
AFTER STRING "doing other things" SET ?status
AFTER EMIT ?status
AFTER IF ?data IS WAITING
OPEN
  WAIT FOR ?data SET ?final
  AFTER EMIT "Waited and got: " & ?final
CLOSE
OR IF ?data IS NULL
OPEN
  EMIT "Data is null or failed"
CLOSE
OR
OPEN
  EMIT "Data arrived: " & ?data
CLOSE
(* IS SET is true for both a WAITING promise and an already-arrived value, so
   the WAITING check must come first — the remaining OR branches then distinguish
   null-or-failed from genuinely arrived *)
Multiple Parallel Promises
FETCH "https://api1.com" SET PROMISE ?async1
AND FETCH "https://api2.com" SET PROMISE ?async2
AFTER STRING "processing" SET ?msg
AFTER EMIT ?msg
AFTER IF ?async1 IS WAITING
OPEN
  WAIT FOR ?async1 3 SECONDS SET ?result1
  OR EMIT "API 1 timed out"
CLOSE
OR
OPEN
  EMIT "API 1: " & ?async1
CLOSE
AFTER IF ?async2 IS WAITING
OPEN
  EMIT "API 2 not ready yet"
CLOSE
OR
OPEN
  EMIT "API 2: " & ?async2
CLOSE

WAIT

WAIT FOR ?var blocks execution until the target variable is no longer WAITING — meaning it has resolved to a value or to NULL. Either outcome unblocks the wait. An explicit timeout in SECONDS raises a catchable ERROR if it expires before resolution — handle it with OR CATCH ERROR. With no explicit timeout, WAIT FOR caps at 300 seconds internally; if nothing resolves by then, it escalates to FATAL instead, since an unbounded wait is treated as a script-authoring failure rather than an environmental one. See Error Reporting & Catching.

WAIT resolves on data or null — it does not wait forever for a specific value. It waits until the variable is no longer WAITING. A null result is a valid resolution.
WAIT Without Timeout
WAIT FOR ?data SET ?result
AFTER EMIT ?result
WAIT With Timeout
WAIT FOR ?data 5 SECONDS SET ?timed
AFTER EMIT ?timed

WAIT and Multivariables

When WAIT FOR targets a multivariable, it waits until every branch has resolved — not just the first. Each branch must reach a value or NULL before execution continues. A timeout, if specified, applies to the entire set of branches collectively.

WAIT on Multivariable Branches
FETCH "https://api1.com" SET PROMISE ?result AND FETCH "https://api2.com" SET PROMISE ?result
(* ?result is a multivariable with two WAITING branches *)
AFTER WAIT FOR ?result SET ?result
(* Blocks until both branches resolve — data or null *)
AFTER COLLAPSE ?result SET ?result
AFTER EMIT ?result(0)
AFTER EMIT ?result(1)
SLEEP is a fixed pause. WAIT is a conditional pause — it unblocks the moment its condition is met, not after a fixed time. Use SLEEP when you know the duration. Use WAIT when you are waiting on an event.
HTTP & Network →